Change Log

Executives and reports endpoints

Released: 2026-09-26

The Company API adds two org-chart reads. Both return ChartNode objects — the same nodes as Find Org Chart — and cost 1 credit per successful call. An unknown company or parent is not charged. Repeating a call, including the next page of reports, is charged again.

• Find executives – GET /v1.2/companies/org-chart/executives returns L1, L2, and the board for a company identified by companyId, domain, or linkedInUrl.
• Find reports – GET /v1.2/companies/org-chart/reports returns the direct reports of a chart node. parentId is that node’s id (p-… or g-…). Pages are 50 reports.

MCP org-chart exploration and OAuth

Released: 2026-09-24

The MCP API server version is 1.2.

• OAuth is fully supported on https://api.theorg.com/v1.1/mcp: protected-resource and authorization-server discovery, OpenID Connect discovery, dynamic client registration, client ID metadata documents, authorization code with PKCE (S256), and userinfo. Scopes are openid, email, and mcp. Clients such as Cursor, Claude, and ChatGPT can connect with the server URL and sign in on The Org. API keys (X-Api-Key, or api_key on the query string) still work. An OAuth connection is its own API key.
• get_company_executive_positions – Company context plus L1, L2, and advisers for one company UUID. Each entry can be a person, a job, or a group.
• get_company_position_reports – Direct reports of one person, job, or group (p-… or g-…), paged at 50.
• search_company_positions – Name or title search on that company’s chart. Results can be people, jobs, or groups. Optional section: orgChart, unplaced, or board.

Those three tools share one charge of 10 credits per API key and company, then they are free for 30 minutes. An unknown company id is not charged. Too few credits returns a tool error and does not open the pass. This is separate from get_org_chart (free iframe URL) and from get_manager / get_reports (1 credit per person lookup).

Per-key rate limits on credit-free endpoints

Released: 2026-09-21

Credit-free REST routes and MCP tools now have per-API-key sliding windows in addition to the global 15 requests per second cap. REST and MCP that return the same data share a bucket.

• 60 requests / 60 seconds – get_company, get_org_chart (also GET /_embeds/org-chart)
• 30 requests / 60 seconds – search_companies (also GET /companies/search), find_person, find_jobs, get_usage (also GET /usage and GET /usage/history), get_lists (also GET /lists)

Over the limit returns 429. See Rate Limiting.

Job and company prospecting APIs

Released: 2026-09-01

The REST API now exposes the same job and company prospecting search used in The Org product, metered like the Position API:

• Job API – POST /v1.1/jobs (alias POST /v1.1/prospect/jobs) searches open job postings. Filters include job titles, functions, types, remote, hiring-company domains/industries/size/funding, job and company locations, org-chart level, and hiring managers. Costs 1 credit per returned row. POST /v1.1/jobs/credit-usage estimates cost without charging.
• Company API – POST /v1.1/companies (alias POST /v1.1/prospect/companies) searches companies by industry, location, region, size, funding, legal status, and whether they are hiring. Costs 1 credit per returned row. POST /v1.1/companies/credit-usage estimates cost without charging.

Replaying the same job or company ID within 24 hours does not consume additional credits. This is separate from the free GET /companies/search name/domain lookup and the free MCP find_jobs / search_companies tools.

MCP person, company LinkedIn, and job lookup tools

Released: 2026-08-13

New tools

The MCP API adds two free lookup tools:

• find_person – Resolve a specific person from The Org’s people index by LinkedIn profile URL/slug, or by fullName plus companyName / companyDomain. Returns positionId, title, LinkedIn URL when known, and company context. Prefer this over find_positions when you already have a LinkedIn URL or a name+company pair.
• find_jobs – Search open job vacancies by The Org job URL (/org/{companySlug}/jobs/{jobSlug}), companySlug + jobSlug, job title/keywords, company scope, or filters such as remote, jobTypes, jobFunctions, and countries. Max 25 results per call. Returns public job URLs like https://theorg.com/org/{companySlug}/jobs/{jobSlug}.

Changes to existing tools

• search_companies now also accepts linkedInUrl (full LinkedIn company URL or bare slug, e.g. stripe).
• Company LinkedIn arguments on get_company / get_org_chart, and person LinkedIn arguments on get_manager / get_reports / find_person, accept bare slugs as well as full URLs.

MCP contact, company, and reporting-line tools

Released: 2026-08-13

New tools

The MCP API adds three tools:

• resolve_contacts – Actively resolve work emails for up to 25 people from find_positions in one call. Costs 1 credit per person newly resolved to an email; people your account has already resolved are free, and people with no resolvable email cost nothing. Also returns any phone numbers on file. If a batch exceeds your remaining balance, only what you can afford is attempted, so a call never overdraws.
• get_company – Enriched company profile by companyId, domain, or linkedInUrl: description, industries, employee range, location, founding year, funding stage and total raised, website and social links, and headcount on The Org. Free. Field values reuse the find_positions filter vocabulary, so a profile can be fed straight back into a people search.
• get_reports – Direct reports of a person, the counterpart to get_manager. Accepts positionId, email, or linkedInUrl. Returns at most 50 reports with totalReports carrying the true count. Costs 1 credit when reports are found.

Changes to existing tools

• get_org_chart now returns an iframe embedUrl (plus name and orgChartUrl) instead of the full chart JSON, which was too large for model context. It is now free rather than 10 credits. To retrieve chart nodes as JSON, use the Company API org chart endpoint over HTTP.
• get_manager now also accepts a positionId, so IDs from find_positions can be used directly instead of round-tripping through an email or LinkedIn URL.
• All embedUrl fields returned by the API (company search, positions, org chart) are now signed URLs of the form /embeds/org-chart/{signature}.
• Every MCP tool now declares a JSON Schema outputSchema in tools/list, and successful tools/call results include a matching structuredContent object alongside the text content block.

Lists API and MCP people/lead list tools

Released: 2026-07-23

Lists API

New Lists API endpoint to read people/lead lists for the authenticated account:

GET https://api.theorg.com/v1.1/lists

Also available on v1.2. Free. Each list includes id, name, slug, url (https://theorg.com/people/lists/{slug}), and positionCount when available.

MCP people/lead list tools

The MCP API includes free tools for Vision people/lead lists:

• get_lists – List owned and shared lists (same data shape as the Lists API).
• create_list – Create a list and optionally add up to 25 positionIds from find_positions in the same call.
• add_to_list – Add up to 25 positionIds to an existing list by listId or slug.

Also documented: MCP find_positions returns at most 25 rows per call (stricter than the Position API page size of up to 1000). Typical flow: find_positions → create_list / add_to_list.

MCP tools expanded

Released: 2026-07-22

The MCP API tool catalog now includes:

• search_companies – Company lookup by name, domain, or email (free).
• find_positions – Full filter schema documented in tools/list (company domains, job titles, departments, names, etc.).

Existing tools (get_org_chart, get_manager, get_usage, find_positions) remain unchanged in behavior. Server info version is now 1.1.

Org Chart v1.2.0

Released: 2026-03-11

Company API – Org Chart v1.2

A new version of the org chart endpoint is available:

GET https://api.theorg.com/v1.2/companies/org-chart

Changes in v1.2.0:

1. No unplaced section – The endpoint no longer supports the unplaced section. Only nodes in the org chart or board are returned.
2. Section parameter – The section query parameter accepts orgChart or board and defaults to orgChart.
3. Leaner nodes – linkedinUrl and workEmail are no longer included in org chart nodes in the response. To get contact details and other fields, enrich nodes by their id using the Position API (e.g. by position id or by looking up the node id).

MCP Integration

Released: 2026-02-24

This release adds support for the Model Context Protocol  (MCP):

• MCP Integration – New documentation section with Introduction and Get started for connecting Claude Desktop and Cursor to The Org’s data.
• MCP API – New endpoint for MCP over Streamable HTTP. See MCP API reference.

POST https://api.theorg.com/v1.1/mcp

Authentication uses the same API key (X-Api-Key header). Initial tools: get_org_chart, get_manager, get_usage, find_positions. See the later changelog entry for the expanded tool set. Credit costs match the existing Company API and Position API.

Org Chart v1.1.0

Released: 2025-10-27

Company API

This release introduces the following changes to the Company API:

GET https://api.theorg.com/v1.1/companies/org-chart

1. The endpoint now returns all nodes associated with a company. The Org maintains a backlog of positions and jobs that are not yet placed in the company org chart, but are still associated with the company. Previously only placed positions and jobs were returned, now both positions and jobs are returned and a section property is added to indicate whether these nodes are part of the orgChart, boardAndAdvisors or whether they are unplaced.

2. A parameter has been added to the endpoint to filter the results by section.

   GET https://api.theorg.com/v1.1/companies/org-chart?domain=theorg.com&section=orgChart

   Parameter	Type	Description	Required
   section	query	Section to filter by	false

   The section can be one of the following:

   • orgChart
   • board
   • unplaced

Migrating from v1 to v1.1

Simply include the section parameter set to orgChart to get the same results as before, the section property can be ingnored in this case.