Contact Research API

The Contact Research API researches a person in real time and returns a full contact record: up to three emails with validation status, up to two direct phones and three company phones with confidence scores, location, tenure, and prior roles.

Endpoint

POST /contacts/research

Credits

1 credit per record submitted. Details

Delivery

Async. Poll or webhook.

Inputs

Send either search results or identities. You do not need to search first.

Input	Use when
`searchResultIds`	You found the contact with the Contact Search API.
`contacts[].email`	You have an email and want phones, title, and company.
`contacts[].liProfileUrl`, `liSalesNavUrl`, `liRecruiterUrl`	You have a LinkedIn URL.
`contacts[].contactName` + `companyName` or `domain`	You have a name and an employer.

Optional fields:

listIds: add each researched contact to one or more Seamless lists.
skipDeduplicationCheck: re-research a contact your org researched recently. This uses credits again.
isJobChange: run a job change check instead. See the Job Change API.

What you get back

Category	Attributes
Emails	`email`, `email1`-`email3`, `email{n}TotalAI` (confidence %), `email{n}EmailAI` (valid / risky / invalid), `personalEmail`
Phones	`contactPhone1`-`2` with `DataType` (mobile, direct) and `TotalAI` confidence, `companyPhone1`-`3`
Person	`firstName`, `lastName`, `fullName`, `jobTitle`, `seniority`, `department`, `image`
Social	`lIProfileUrl`, `lISalesNavUrl`, `lIRecruiterUrl`
Location	`contactLocation` (city, state, postal code, country, ISO codes, timezone), `localTime`
Tenure	`startedAtCurrentCompany`, `titleStartedAt`, `timeAtRole`, `timeAtCompany`, `jobHistory[]`, `formerCompany`, `formerTitle`
Company	`companyName`, `companyDomain`, `companyIndustry`, `companySize`, `companyStaffCount`, `companyRevenue`, `companyLocation`, `sicCode`, `naicsCode`
Signals	`jobChangeAlert`, `newsAndEvents[]`, `companyFundingTotal`, `companyLatestFundingDate`, `companyType`, `stockTicker`

The Data dictionary lists every field.

Example

curl -X POST https://api.seamless.ai/api/client/v1/contacts/research \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [ { "email": "jane.doe@acme.com" } ] }'

curl -X POST https://api.seamless.ai/api/client/v1/contacts/research \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [ { "liProfileUrl": "https://www.linkedin.com/in/janedoe" } ] }'

curl -X POST https://api.seamless.ai/api/client/v1/contacts/research \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [ { "contactName": "Jane Doe", "domain": "acme.com" } ] }'

curl -X POST https://api.seamless.ai/api/client/v1/contacts/research \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchResultIds": ["ctc_sr_..."] }'

The response returns one requestId per contact. Poll until status is done:

curl "https://api.seamless.ai/api/client/v1/contacts/research/poll?requestIds=REQUEST_ID" \
  -H "Token: $SEAMLESS_API_KEY"

Response (trimmed)

{
  "success": true,
  "data": [
    {
      "requestId": "...",
      "status": "done",
      "contact": {
        "fullName": "Jane Doe",
        "jobTitle": "VP, Revenue Operations",
        "email": "jane.doe@acme.com",
        "email1TotalAI": "98",
        "email1EmailAI": "valid",
        "contactPhone1": "+1 512 555 0100",
        "contactPhone1DataType": "mobile",
        "companyName": "Acme Corp",
        "companyDomain": "acme.com",
        "contactLocation": { "city": "Austin", "stateAbbr": "TX", "countryAlpha2": "US" }
      }
    }
  ]
}

Common poll statuses: queued, researching, done, duplicate, not found, missing, and error. A duplicate status means your org already researched this contact. Read it from the My Contact Data API instead of paying to research it again.

Catalog

Identity resolution

Search

Contact Search filters

Company Search filters

Research

My data

Platform

Coming soon

Contact Research API

Endpoint

Credits

Delivery

Inputs

What you get back

Example

Endpoint

Credits

Delivery

​Inputs

​What you get back

​Example

​Related

Inputs

What you get back

Example

Related