ÂÜÀòÂÒÂ×

Log inSign up

The Org API reference

Terms of Service

Introduction

Welcome to our API documentation. Our REST API provides unrestricted structured access to the worlds largest database of organizational charts. Currently the main entrypoint is though a company domain name.

Endpoint

The API is served from https://api.theorg.com/v1.

Authentication

The API uses API keys to authenticate requests. You can view and manage your API keys in your Subscription Center.

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

You can make 15 requests per second to a single endpoint of our API.

Org chart API

/org/{domain}

Get raw organizational data along with company level information that can be used for internal CRM enrichment, trend analysis, etc.

path Parameters
domain
required
string

The domain name of the company. Example: theorg.com. This attribute is case-insensitive.

Responses

Response Schema: application/json
object (Company)
object (ErrorResponse)

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": {
    }
}

/positions/managers

Get the manager from a position by email. This endpoint is useful for finding the manager of a position within an organization. If multiple managers are returned they are considered to be co-managers.

query Parameters
email
required
string

The email address of the position you want to find the manager for. Example: andreas@theorg.com

Responses

Response Schema: application/json
object (ManagerFindingResponse)
object (ErrorResponse)

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": {
    }
}

Prospecting API

/prospect/search

Enjoy the full prospecting experience as an API. This endpoint allows you to search for positions with their contact information based on a wide range of filters.

Request Body schema: application/json
limit
number <int32>

The maximum number of results to return, the maximum page size is 1000.

offset
number <int32>

The offset of the results, the largest offset is 10,000.

object

The filters to apply to the search

Responses

Response Schema: application/json
object
object (ErrorResponse)

Request samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": {
    }
}

/prospect/search/credit-usage

This endpoint can help estimate the credit usage of a single request to the prospecting api, call this with the required filters to understand the cost of a single request.

Request Body schema: application/json
limit
number <int32>

The maximum number of results to return, the maximum page size is 1000.

offset
number <int32>

The offset of the results, the largest offset is 10,000.

object

The filters to apply to the search

Responses

Response Schema: application/json
object
object (ErrorResponse)

Request samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": {
    }
}

Usage API

/usage

Get information about the usage within the current billing period. This endpoint can be used to monitor your usage and to check your remaining credits.

Responses

Response Schema: application/json
object (UsageResponse)
object (ErrorResponse)

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": {
    }
}

/usage/{endpoint}/history

Get historical usage data for a specific endpoint.

path Parameters
endpoint
required
string

The endpoint you want to check. Example: manager_api. Possible values are position_api, contact_api, embed_api, manager_api, org_chart_api.

query Parameters
from
required
string

The start date of the period you want to check. Example: 2021-01-01. The date format is YYYY-MM-DD.

to
required
string

The end date of the period you want to check. Example: 2021-01-31. The date format is YYYY-MM-DD.

interval
string

The interval of the data you want to check. Possible values are daily, monthly. Default: daily.

Responses

Response Schema: application/json
object (UsageHistoryResponse)
object (ErrorResponse)

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": {
    }
}

Embed API

/companies/search

Embed org charts directly on your website or enrich your presentaions or CRM. This service searches companies by either name or a domain and returns embed urls wich can be added to iframes or shared. You must supply either "domain" or "email".

query Parameters
domain
string

A search parameter for a company website or email domain. Example: microsoft.com. This attribute is case-insensitive

email
string

A search parameter for a company email. Example: bill@microsoft.com. If provided the "embedUrl" might contain an additional pointer which highlights a position in the org chart. This attribute is case-insensitive

Responses

Response Schema: application/json
Array of objects (CompanySearchResult)

Response samples

Content type
application/json
{
  • "companies": [
    ]
}