Contacts API
Start a contact lookup and poll it, or list contacts this account has already resolved. The same operations are available as MCP tools: start_contact_resolution, get_contact_resolution, and list_resolved_contacts. See the MCP API.
A lookup runs against a person who already exists in The Org. Pass positionId from find_person or the Position API. resolve_contacts is still the synchronous email batch for up to 25 position ids.
Start a resolution
POST https://api.theorg.com/v1.2/contacts/resolutions| Parameter | Value |
|---|---|
| Url | https://api.theorg.com/v1.2/contacts/resolutions |
| Method | POST |
| Body | Request body |
| Cost | Debited on start. See Credits |
The call returns as soon as the job is stored. A returned id is not a finished lookup. Poll Get a resolution, or pass callbackUrl for a server you control.
Request body
Provide at least one of includeEmail, includePhone, and includeLinkedIn. Identify the person with positionId, or linkedinUrl, or firstName and lastName together with companyDomain or companyName.
| Parameter | Type | Description | Required |
|---|---|---|---|
positionId | integer | Person id from find_person or the Position API | false |
firstName | string | Used with lastName and a company field when positionId is omitted | false |
lastName | string | Used with firstName and a company field when positionId is omitted | false |
companyDomain | string | Company domain, for example stripe.com | false |
companyName | string | Company name, used when companyDomain is omitted | false |
linkedinUrl | string | Person LinkedIn profile URL. Used when positionId is omitted | false |
callbackUrl | string | Public https URL. Receives one resolutionDone POST when every requested channel is finished | false |
includeEmail | boolean | Look up the work email | false |
includePhone | boolean | Look up the phone number | false |
includeLinkedIn | boolean | Reveal the LinkedIn URL already stored on the person. This does not scrape a profile | false |
positionId wins when it is present. Otherwise a LinkedIn URL is matched, then firstName + lastName with companyDomain or companyName. Zero matches returns PERSON_NOT_FOUND. More than one match returns AMBIGUOUS_PERSON. Call find_person and pass positionId.
Credits
| Channel | Debited on start | Refunded when |
|---|---|---|
| 1 | The lookup finishes with no verified email | |
| Phone | 8 | The lookup finishes with no phone number |
| 1 | The person has no stored LinkedIn URL |
A channel this account has already revealed is free and is not debited. Every other requested channel is debited in full before the id is returned, including a lookup that might later miss. A miss refunds that channel only. A stored email, phone, or LinkedIn URL keeps the charge. The start call rejects with 402 and MISSING_FUNDS when the wallet cannot cover the billable total, and it does not start the job.
Example
curl --location 'https://api.theorg.com/v1.2/contacts/resolutions' \
--header 'X-Api-Key: **********************a02e' \
--header 'Content-Type: application/json' \
--data '{
"positionId": 179671,
"includeEmail": true,
"includePhone": true,
"callbackUrl": "https://example.com/hooks/theorg"
}'{
"data": {
"id": "enr_0f5b1c2d3e4f5678901234abcdef5678"
}
}Get a resolution
GET https://api.theorg.com/v1.2/contacts/resolutions/{id}| Parameter | Value |
|---|---|
| Url | https://api.theorg.com/v1.2/contacts/resolutions/{id} |
| Method | GET |
| Cost | Free |
| Rate limit | 60 requests / 60 seconds, shared with get_contact_resolution |
The id is account-scoped. An id from another account is 404.
| HTTP | enrichmentStatus | Meaning |
|---|---|---|
| 200 | done | Every requested channel finished. data holds the results. |
| 202 | in-progress | At least one channel is still running. data is {}. |
| 400 | failed | The job failed. code and reason say why. Credits for open channels were returned. |
| 404 | Unknown id. |
Done
curl --location 'https://api.theorg.com/v1.2/contacts/resolutions/enr_0f5b1c2d3e4f5678901234abcdef5678' \
--header 'X-Api-Key: **********************a02e'{
"data": {
"enrichmentId": "enr_0f5b1c2d3e4f5678901234abcdef5678",
"enrichmentStatus": "done",
"input": {
"positionId": 179671,
"includeEmail": true,
"includePhone": true
},
"creditsCharged": 9,
"creditsRefunded": 8,
"data": {
"email": {
"email": "ada@stripe.com",
"notFound": false,
"status": "deliverable"
},
"phone": {
"notFound": true
}
}
}
}Channels you did not request are omitted. A finished channel with nothing stored is { "notFound": true } and that channel’s credits are in creditsRefunded. status on an email is deliverable, risky, or undeliverable when known. A phone result uses phone and, when more than one number was stored, additionalPhones. A LinkedIn result uses url.
In progress
HTTP 202. data inside the resolution is empty. Poll again.
{
"data": {
"enrichmentId": "enr_0f5b1c2d3e4f5678901234abcdef5678",
"enrichmentStatus": "in-progress",
"input": { "positionId": 179671, "includeEmail": true },
"creditsCharged": 1,
"creditsRefunded": 0,
"data": {}
}
}Callback
When callbackUrl is set, The Org sends one POST after every requested channel is terminal. The body is the same object as a done poll, wrapped as { "type": "resolutionDone", "data": { ... } }. callbackUrl must be https and must not be a loopback, link-local, or private address. A failed delivery is stored on the job and does not change enrichmentStatus. Agents should poll get_contact_resolution instead of depending on the callback.
List resolved contacts
GET https://api.theorg.com/v1.2/contacts| Parameter | Value |
|---|---|
| Url | https://api.theorg.com/v1.2/contacts |
| Method | GET |
| Cost | Free. Does not start a lookup |
| Rate limit | 30 requests / 60 seconds, shared with list_resolved_contacts |
Returns contacts this account has already resolved. Unrevealed email, phone, and LinkedIn values are omitted.
| Query | Type | Description |
|---|---|---|
name | string | Person name |
role | string | Role or title |
companyName | string | Company name |
positionId | integer | Restrict to one person |
limit | integer | Page size, 1–100. Default 25 |
cursor | string | nextCursor from the previous page |
curl --location 'https://api.theorg.com/v1.2/contacts?name=ada&companyName=Stripe&limit=25' \
--header 'X-Api-Key: **********************a02e'{
"data": {
"contacts": [
{
"positionId": 179671,
"fullName": "Ada Lovelace",
"role": "VP Engineering",
"companyName": "Stripe",
"email": "ada@stripe.com",
"linkedinUrl": "https://www.linkedin.com/in/ada"
}
],
"nextCursor": null
}
}Pass nextCursor back as cursor. It is null on the last page.
Errors
Start and list errors use { "code", "message" } rather than the error object described in Key Concepts. A failed poll is HTTP 400 with the resolution object under data, including enrichmentStatus: "failed", code, and reason.
| HTTP | code | When |
|---|---|---|
| 400 | MISSING_INPUTS | No channel was requested, or the person fields are incomplete |
| 400 | PERSON_NOT_FOUND | No matching person. Pass positionId from find_person |
| 400 | AMBIGUOUS_PERSON | More than one person matched. Pass positionId |
| 400 | BAD_CALLBACK_URL | callbackUrl is not a public https URL |
| 400 | BAD_PARAMS | limit is outside 1–100 |
| 400 | BAD_CURSOR | cursor cannot be read |
| 402 | MISSING_FUNDS | The wallet cannot cover the channels that would be debited |
| 404 | NOT_FOUND | The resolution id is missing or belongs to another account |
| 503 | FAILED_TO_PROCESS | The lookup could not be started. Credits for the request were returned |
| 503 | SYSTEM_BUSY | Retry the start request |