Key Concepts
Endpoint
The API is accessed via:
https://api.theorg.com/v1Authentication
The API uses API keys to authenticate requests. You can view and manage your API keys via the Developers section in Manage account .
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.
You can make 15 requests per second to a single endpoint of our API across API keys within an account.
Accounts exceeding the rate will encounter 429 ("Too Many Requests") responses.
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 |
| /positions | Returns rich information about positions | 1 per returned row |
Requests can be replayed any amount of times within 24 hours of the initial request at no additional cost.
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 account , 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 | 10,000 |
| Basic | $0.04 | 10,000 |
| Premium | $0.03 | 10,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\""
}
}