Skip to Content

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
ParameterValue
Urlhttps://api.theorg.com/v1.2/contacts/resolutions 
MethodPOST
BodyRequest body
CostDebited 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.

ParameterTypeDescriptionRequired
positionIdintegerPerson id from find_person or the Position APIfalse
firstNamestringUsed with lastName and a company field when positionId is omittedfalse
lastNamestringUsed with firstName and a company field when positionId is omittedfalse
companyDomainstringCompany domain, for example stripe.comfalse
companyNamestringCompany name, used when companyDomain is omittedfalse
linkedinUrlstringPerson LinkedIn profile URL. Used when positionId is omittedfalse
callbackUrlstringPublic https URL. Receives one resolutionDone POST when every requested channel is finishedfalse
includeEmailbooleanLook up the work emailfalse
includePhonebooleanLook up the phone numberfalse
includeLinkedInbooleanReveal the LinkedIn URL already stored on the person. This does not scrape a profilefalse

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

ChannelDebited on startRefunded when
Email1The lookup finishes with no verified email
Phone8The lookup finishes with no phone number
LinkedIn1The 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

Start an email and phone lookup
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}
ParameterValue
Urlhttps://api.theorg.com/v1.2/contacts/resolutions/{id} 
MethodGET
CostFree
Rate limit60 requests / 60 seconds, shared with get_contact_resolution

The id is account-scoped. An id from another account is 404.

HTTPenrichmentStatusMeaning
200doneEvery requested channel finished. data holds the results.
202in-progressAt least one channel is still running. data is {}.
400failedThe job failed. code and reason say why. Credits for open channels were returned.
404Unknown id.

Done

Poll a resolution
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
ParameterValue
Urlhttps://api.theorg.com/v1.2/contacts 
MethodGET
CostFree. Does not start a lookup
Rate limit30 requests / 60 seconds, shared with list_resolved_contacts

Returns contacts this account has already resolved. Unrevealed email, phone, and LinkedIn values are omitted.

QueryTypeDescription
namestringPerson name
rolestringRole or title
companyNamestringCompany name
positionIdintegerRestrict to one person
limitintegerPage size, 1–100. Default 25
cursorstringnextCursor from the previous page
List resolved contacts
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.

HTTPcodeWhen
400MISSING_INPUTSNo channel was requested, or the person fields are incomplete
400PERSON_NOT_FOUNDNo matching person. Pass positionId from find_person
400AMBIGUOUS_PERSONMore than one person matched. Pass positionId
400BAD_CALLBACK_URLcallbackUrl is not a public https URL
400BAD_PARAMSlimit is outside 1–100
400BAD_CURSORcursor cannot be read
402MISSING_FUNDSThe wallet cannot cover the channels that would be debited
404NOT_FOUNDThe resolution id is missing or belongs to another account
503FAILED_TO_PROCESSThe lookup could not be started. Credits for the request were returned
503SYSTEM_BUSYRetry the start request
Last updated on