> ## 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.

> [card] Endpoint
>
> `POST /contacts/research`

> [card] Credits
>
> By default 1 for email, 5 for phone,
> 6 for both, per contact.
> [Details](https://docs.seamless.ai/core-concepts/credits.md#contact-research-costs)

> [card] Delivery
>
> Async. [Poll](https://docs.seamless.ai/api-reference/v1/contact-research/poll-contact-research.md) or [webhook](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md).

## 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](https://docs.seamless.ai/api-catalog/contact-search.md). |
| `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.
* `researchTypes`: research `["email"]`, `["phone"]`, or both for every contact. Omit it to use your Contact Data settings. See [Contact research costs](https://docs.seamless.ai/core-concepts/credits.md#contact-research-costs).
* `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](https://docs.seamless.ai/api-catalog/job-changes.md).

## 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](https://docs.seamless.ai/api-catalog/data-dictionary.md) 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": ["708dbb34-3849-3c06-abd1-238b9a0295b3"]}'
```

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](https://docs.seamless.ai/api-catalog/my-contact-data.md) instead of paying to research it again.
> `not found` means no match for the identifiers; `missing` means the server
> has no record of that `requestId`.

For a single contact, `POST /contacts/research/single` takes one `searchResultId` (or one `contact` object, optionally with `isJobChange`) and returns one `requestId` to poll the same way.

For Python, JavaScript, and other languages, see [Research contacts](https://docs.seamless.ai/api-reference/v1/contact-research/research-contacts.md) in the API reference.

## Related

* [Receive results with webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md)
* [Research without search](https://docs.seamless.ai/core-concepts/research-without-search.md)
* [API reference: Research contacts](https://docs.seamless.ai/api-reference/v1/contact-research/research-contacts.md)


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