> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Research API

> Turn a name and company, an email, or a LinkedIn URL into verified work emails, direct dials, mobile numbers, location, and job history.

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](/rate-limits-and-credits)

> **Delivery**
>
> Async. [Poll](/api-reference/v1/contact-research/poll-contact-research) or [webhook](/receive-research-results-with-webhooks).

## 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](/api-catalog/contact-search). |
| `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](/api-catalog/job-changes).

## 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](/api-catalog/data-dictionary) lists every field.

## Example

```bash By email theme={null}
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" } ] }'
```

```bash By LinkedIn URL theme={null}
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" } ] }'
```

```bash By name + domain theme={null}
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" } ] }'
```

```bash From search theme={null}
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`:

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

```json Response (trimmed) theme={null}
{
  "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" }
      }
    }
  ]
}
```

> [!NOTE]
>
> 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](/api-catalog/my-contact-data) instead of paying to research it again.

## Related

* [Receive results with webhooks](/receive-research-results-with-webhooks)
* [Research without search](/research-without-search)
* [API reference: Research contacts](/api-reference/v1/contact-research/research-contacts)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.