The Org API reference

Introduction

Welcome to the 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. The API is avaliable to Enterprise Plan customers.

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 10 requests per second to a single endpoint of our API.

Company Org Chart API

This service returns a full company org chart along with company level information that can be used for internal identification and deduplication.

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": {"id": "6784cbe5-b023-4eeb-9200-232e405d8dfa",
"name": "Starfleet",
"domains": ["starfleet.com",
"starfleet.org"
],
"embedUrl": "https://theorg.com/org/starfleet/embed",
"positions": [{"id": 4300032,
"slug": "james-t-kirk",
"name": "James T. Kirk",
"title": "Admiral, Fleet operations",
"managerIds": [4300033
],
"url": "https://theorg.com/org/starfleet/org-chart/james-t-kirk",
"profilePhotoUrl": "https://cdn.theorg.com/e4df08a9-085a-4364-ba3a-626129f30749_thumb.jpg",
"linkedInUrl": "https://www.linkedin.com/in/james-t-kirk-123456789",
"twitterUrl": "https://twitter.com/jamestkirk",
"facebookUrl": "https://www.facebook.com/jamestkirk",
"level": 2,
"startDate": "2269-03-01"
}
]
},
"error": {"code": 404,
"reason": "Not Found"
}
}

Company Search API

This service searches companies by either name or a domain and returns embed urls and meta information. You must supply either "q", "domain" or "email".

query Parameters

q	string A search query for a company name. Example: microsoft. This attribute is case-insensitive
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": [{"id": "6784cbe5-b023-4eeb-9200-232e405d8dfa",
"name": "Starfleet",
"logoUrl": "https://cdn.theorg.com/e4df08a9-085a-4364-ba3a-626129f30749_thumb.jpg",
"domains": ["starfleet.com",
"starfleet.org"
],
"orgChartUrl": "https://theorg.com/org/starfleet",
"embedUrl": "https://theorg.com/org/starfleet/embed"
}
]
}

People Contact API

This service provides contact information for a list of position ids and can be used together with the Company Org Chart API.

Request Body schema: application/json

positionIds

Array of numbers <int32> [ items <int32 > ]

List of position ids

Responses

Response Schema: application/json

	object (ContactsResult)
	object (ErrorResponse)

Request samples

Payload

Content type

application/json

{"positionIds": [4300032
]
}

Response samples

Content type

application/json

{"data": {"creditsUsed": 1,
"results": [{"positionId": 4300032,
"emails": [{"email": "kirk@starfleet.com",
"emailType": "professional",
"verification": "verified"
}
],
"phoneNumbers": ["+15555555555"
]
}
]
},
"error": {"code": 404,
"reason": "Not Found"
}
}