Key Concepts
Endpoint
The API is accessed via:
https://api.theorg.com/v1.1Authentication
The API uses API keys to authenticate requests. You can view and manage your API keys via the Developers section in Manage subscription .
Authentication to the API is performed by passing the key in a header called X-Api-Key.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Rate Limiting
We manage API usage through rate limits to ensure fair access and optimal performance for all users.
Every API key can make 15 requests per second across all endpoints. Requests over that cap return 429 ("Too Many Requests").
Credit-free REST routes and MCP tools also have per-API-key sliding windows. REST and MCP that return the same data share a bucket, so calling both does not double the allowance.
| Bucket | Limit | REST | MCP |
|---|---|---|---|
get_company | 60 requests / 60 seconds | — | get_company |
get_org_chart | 60 requests / 60 seconds | GET /_embeds/org-chart | get_org_chart |
search_companies | 30 requests / 60 seconds | GET /companies/search | search_companies |
find_person | 30 requests / 60 seconds | — | find_person |
find_jobs | 30 requests / 60 seconds | — | find_jobs |
get_usage | 30 requests / 60 seconds | GET /usage, GET /usage/history | get_usage |
get_lists | 30 requests / 60 seconds | GET /lists | get_lists |
Paid endpoints stay on credits plus the global 15 req/s cap. Exceeding a free-tool bucket also returns 429.
Credits and Usage
The API uses a universal credit system where API credits can be used across endpoints.
All accounts have 100 API credits per month.
Enterprise customers may have a custom monthly credit allowance or even unlimited credits subject to the rate limits and fair usage policy. Talk to sales for more info.
Various endpoints have different credit costs below is an overview of how credits apply:
| API Endpoint | Description | Credit cost |
|---|---|---|
| /companies/chart | Returning full org charts for companies | 10 per successful request |
| /companies/chart/managers | Returns the manager of a given report | 1 per successful find |
| /companies/org-chart/executives | Top of the org chart (L1, L2, and board) | 1 per successful request |
| /companies/org-chart/reports | Direct reports of a chart node (parentId) | 1 per successful request |
| /positions | Returns rich information about positions | 1 per returned row |
| /jobs | Returns open job postings | 1 per returned row |
| /companies | Returns companies matching filters | 1 per returned row |
| /lists | Lists people/lead lists for the account | Free |
| MCP org-chart exploration | get_company_executive_positions, get_company_position_reports, and search_company_positions for one company | 10 per API key per company, then free for 30 minutes |
Metered REST requests can be replayed any number of times within 24 hours of
the initial request at no additional cost. Executives and reports
(/companies/org-chart/executives and /companies/org-chart/reports) are the
exception: each successful call costs 1 credit, including repeats. MCP
org-chart exploration is separate: 10 credits per API key and company, then
free for 30 minutes.
Non-enterprise accounts don’t support overages and requests that exceed the credit limits will see a 402 (Payment Required) response.
Buying More Credits
Credits can be bought via the Developers section in Manage subscription , by clicking Buy credits. All monthly credits are used before any additional credits are applied.
Credit costs are based on subscription level:
| Subscription Tier | Pr. credit cost | Monthly Limit |
|---|---|---|
| Free | $0.05 | 240,000 |
| Basic | $0.04 | 240,000 |
| Premium | $0.03 | 240,000 |
| Enterprise | $0.02 | Unlimited |
Common response codes
The API follows the REST best practices and uses standard HTTP response codes to indicate the success or failure of a request.
| Code | Description |
|---|---|
| 200 | OK |
| 400 | Bad Request - The request is submitted incorrectly either missing a property or using a wrong enum etc. |
| 401 | Unauthorized - Missing an API key or the key has expired. |
| 402 | Payment Required - all credits and overages (if applicable) have been exhausted. |
| 404 | Not Found - the service was not able to find the requested resource and no credits were used. |
| 429 | Too Many Requests - if a given API key exceeds the request rates outlined here. |
| 500 | Internal Server Error - these responses are logged, but should be reported if the error persists. |
| 503 | Service Unavailable - transient service issues, we apologize, the request can be retried, preferably with a backoff. |
| 504 | Gateway Timeout - transient service issues, we apologize, the request can be retried, preferably with a backoff. |
Error responses
If an error occurs, the API will return a JSON object with the following properties:
| Property | Description |
|---|---|
error.code | The HTTP status code as a number |
error.reason | A comprehensive reason for the error |
Example
{
"error": {
"code": 400,
"reason": "Missing the required header: \"x-api-key\""
}
}