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

# Authenticate and make your first Seamless API call

> Authenticate with an API key, search for a company or contact, submit a research request, and retrieve enriched results using polling — in three steps.

The Seamless API follows a three-step flow: search for the record you want, submit it for research, and retrieve the enriched result. Authentication is handled by passing your API key in a `Token` request header. This guide walks through each step using companies and contacts as parallel examples, with code samples in curl, Python, and Node.js.

## Prerequisites

Before you begin:

* Create a [Seamless.AI](https://seamless.ai) account.
* Go to [Settings → Public API → API Key](https://login.seamless.ai/settings/public-api) and create a connection.
* Install `curl`, Python (`requests` library), or Node.js (`fetch` is built in from Node 18+).

> [!NOTE]
>
> Store your API key in an environment variable. The examples below reference
> it as `$SEAMLESS_API_KEY`.

**1. Search for a company or contact**

Search returns a list of matching records. Each result includes a `searchResultId` you'll use in the next step.

> [tab] Company
>
> ```bash curl theme={null}
> curl -X POST https://api.seamless.ai/api/client/v1/search/companies \
>   -H "Content-Type: application/json" \
>   -H "Token: $SEAMLESS_API_KEY" \
>   -d '{
>     "companyName": ["Acme Corp"],
>     "limit": 5
>   }'
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.post(
>     "https://api.seamless.ai/api/client/v1/search/companies",
>     headers={
>         "Content-Type": "application/json",
>         "Token": os.environ["SEAMLESS_API_KEY"],
>     },
>     json={
>         "companyName": ["Acme Corp"],
>         "limit": 5,
>     },
> )
> print(response.json())
> ```
>
> ```javascript Node.js theme={null}
> const response = await fetch(
>   "https://api.seamless.ai/api/client/v1/search/companies",
>   {
>     method: "POST",
>     headers: {
>       "Content-Type": "application/json",
>       Token: process.env.SEAMLESS_API_KEY,
>     },
>     body: JSON.stringify({
>       companyName: ["Acme Corp"],
>       limit: 5,
>     }),
>   }
> );
> const data = await response.json();
> console.log(data);
> ```
>
> Example response:
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "searchResultId": "YOUR_SEARCH_RESULT_ID",
>       "name": "Acme Corp",
>       "domain": "acmecorp.com",
>       "industries": ["Information Technology and Services"],
>       "staffCountRange": "51 - 200",
>       "revenueRange": "$20M - $50M"
>     }
>   ],
>   "supplementalData": {
>     "isMore": true,
>     "total": 12,
>     "perPage": 5,
>     "nextToken": "eyJwYWdlIjoyLCJzZWFyY2hJZCI6ImFiYzEyMyJ9"
>   }
> }
> ```
>
> Save the `searchResultId` from the record you want to enrich. You'll pass it to the research endpoint in step 2.

> [tab] Contact
>
> ```bash curl theme={null}
> curl -X POST https://api.seamless.ai/api/client/v1/search/contacts \
>   -H "Content-Type: application/json" \
>   -H "Token: $SEAMLESS_API_KEY" \
>   -d '{
>     "jobTitle": ["Chief Technology Officer"],
>     "companyName": ["Acme Corp"],
>     "limit": 5
>   }'
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.post(
>     "https://api.seamless.ai/api/client/v1/search/contacts",
>     headers={
>         "Content-Type": "application/json",
>         "Token": os.environ["SEAMLESS_API_KEY"],
>     },
>     json={
>         "jobTitle": ["Chief Technology Officer"],
>         "companyName": ["Acme Corp"],
>         "limit": 5,
>     },
> )
> print(response.json())
> ```
>
> ```javascript Node.js theme={null}
> const response = await fetch(
>   "https://api.seamless.ai/api/client/v1/search/contacts",
>   {
>     method: "POST",
>     headers: {
>       "Content-Type": "application/json",
>       Token: process.env.SEAMLESS_API_KEY,
>     },
>     body: JSON.stringify({
>       jobTitle: ["Chief Technology Officer"],
>       companyName: ["Acme Corp"],
>       limit: 5,
>     }),
>   }
> );
> const data = await response.json();
> console.log(data);
> ```
>
> The response structure mirrors the company search. Save the `searchResultId` for the contact you want to enrich.

**2. Submit a research request**

Pass one or more `searchResultIds` to the research endpoint. The API returns a `requestId` for each submitted record — you'll use this to retrieve results in step 3.

> [tab] Company
>
> ```bash curl theme={null}
> curl -X POST https://api.seamless.ai/api/client/v1/companies/research \
>   -H "Content-Type: application/json" \
>   -H "Token: $SEAMLESS_API_KEY" \
>   -d '{
>     "searchResultIds": ["YOUR_SEARCH_RESULT_ID"]
>   }'
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.post(
>     "https://api.seamless.ai/api/client/v1/companies/research",
>     headers={
>         "Content-Type": "application/json",
>         "Token": os.environ["SEAMLESS_API_KEY"],
>     },
>     json={
>         "searchResultIds": ["YOUR_SEARCH_RESULT_ID"],
>     },
> )
> print(response.json())
> ```
>
> ```javascript Node.js theme={null}
> const response = await fetch(
>   "https://api.seamless.ai/api/client/v1/companies/research",
>   {
>     method: "POST",
>     headers: {
>       "Content-Type": "application/json",
>       Token: process.env.SEAMLESS_API_KEY,
>     },
>     body: JSON.stringify({
>       searchResultIds: ["YOUR_SEARCH_RESULT_ID"],
>     }),
>   }
> );
> const data = await response.json();
> console.log(data);
> ```

> [tab] Contact
>
> ```bash curl theme={null}
> curl -X POST https://api.seamless.ai/api/client/v1/contacts/research \
>   -H "Content-Type: application/json" \
>   -H "Token: $SEAMLESS_API_KEY" \
>   -d '{
>     "searchResultIds": ["YOUR_SEARCH_RESULT_ID"]
>   }'
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.post(
>     "https://api.seamless.ai/api/client/v1/contacts/research",
>     headers={
>         "Content-Type": "application/json",
>         "Token": os.environ["SEAMLESS_API_KEY"],
>     },
>     json={
>         "searchResultIds": ["YOUR_SEARCH_RESULT_ID"],
>     },
> )
> print(response.json())
> ```
>
> ```javascript Node.js theme={null}
> const response = await fetch(
>   "https://api.seamless.ai/api/client/v1/contacts/research",
>   {
>     method: "POST",
>     headers: {
>       "Content-Type": "application/json",
>       Token: process.env.SEAMLESS_API_KEY,
>     },
>     body: JSON.stringify({
>       searchResultIds: ["YOUR_SEARCH_RESULT_ID"],
>     }),
>   }
> );
> const data = await response.json();
> console.log(data);
> ```

Both endpoints return **HTTP 202 Accepted** with the same JSON body:

```json theme={null}
{
  "success": true,
  "requestIds": ["YOUR_REQUEST_ID"]
}
```

> [!NOTE]
>
> You can submit multiple `searchResultIds` in a single request. Each one gets its own `requestId` in the response array.

**3. Retrieve results by polling**

Call the poll endpoint with your `requestId` to check research status. Research runs asynchronously, so poll every few seconds until the status is `done`.

> [tab] Company
>
> ```bash curl theme={null}
> curl -X GET "https://api.seamless.ai/api/client/v1/companies/research/poll?requestIds=YOUR_REQUEST_ID" \
>   -H "Token: $SEAMLESS_API_KEY"
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.get(
>     "https://api.seamless.ai/api/client/v1/companies/research/poll",
>     headers={"Token": os.environ["SEAMLESS_API_KEY"]},
>     params={"requestIds": "YOUR_REQUEST_ID"},
> )
> print(response.json())
> ```
>
> ```javascript Node.js theme={null}
> const params = new URLSearchParams({ requestIds: "YOUR_REQUEST_ID" });
> const response = await fetch(
>   `https://api.seamless.ai/api/client/v1/companies/research/poll?${params}`,
>   {
>     headers: {
>       Token: process.env.SEAMLESS_API_KEY,
>     },
>   }
> );
> const data = await response.json();
> console.log(data);
> ```

> [tab] Contact
>
> ```bash curl theme={null}
> curl -X GET "https://api.seamless.ai/api/client/v1/contacts/research/poll?requestIds=YOUR_REQUEST_ID" \
>   -H "Token: $SEAMLESS_API_KEY"
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.get(
>     "https://api.seamless.ai/api/client/v1/contacts/research/poll",
>     headers={"Token": os.environ["SEAMLESS_API_KEY"]},
>     params={"requestIds": "YOUR_REQUEST_ID"},
> )
> print(response.json())
> ```
>
> ```javascript Node.js theme={null}
> const params = new URLSearchParams({ requestIds: "YOUR_REQUEST_ID" });
> const response = await fetch(
>   `https://api.seamless.ai/api/client/v1/contacts/research/poll?${params}`,
>   {
>     headers: {
>       Token: process.env.SEAMLESS_API_KEY,
>     },
>   }
> );
> const data = await response.json();
> console.log(data);
> ```

When research is still running, the response looks like this:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "requestId": "YOUR_REQUEST_ID",
      "status": "researching"
    }
  ]
}
```

When research is complete, the `status` changes to `done` and the full record appears in the response:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "requestId": "YOUR_REQUEST_ID",
      "status": "done",
      "company": {
        "apiResearchId": "YOUR_REQUEST_ID",
        "name": "Acme Corp",
        "domain": "acmecorp.com",
        "description": "Acme Corp is a leading provider of innovative business solutions.",
        "foundedOn": "2015-01-01",
        "industries": "Information Technology and Services,Computer Software",
        "annualRevenue": "35000000",
        "revenueRange": "$20M - $50M",
        "staffCount": "125",
        "staffCountRange": "51 - 200",
        "phones": "+1-555-555-0100",
        "phonesAiScores": "98",
        "linkedInProfileUrl": "https://www.linkedin.com/company/acme-corp/",
        "linkedInId": "9876543",
        "topTechnologies": "Salesforce,HubSpot,Marketo",
        "sicCode": "7372",
        "location": {
          "street1": "100 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postCode": "94105",
          "country": "United States",
          "countryAbbr": "US",
          "countryAlpha2": "US",
          "countryAlpha3": "USA",
          "fullString": "100 Main St, San Francisco, CA 94105, United States"
        },
        "createdAt": "2026-01-15T10:30:00.000Z",
        "updatedAt": "2026-01-15T10:30:00.000Z"
      }
    }
  ]
}
```

### Poll status values

| Status | Applies to | Meaning |
| - | - | - |
| `queued` | Contacts only | Accepted, not started. Poll again in a few seconds. |
| `researching` | Both | Still processing. Poll again in a few seconds. |
| `done` | Both | Research complete. Full record is available. |
| `missing` | Both | Contacts: the `requestId` is unknown. Companies: not finished yet, or the `requestId` is unknown. |
| `not found` | Contacts only | No match for the identifiers you sent. |
| `error` | Both | Could not process. Check credits and license. |
| `duplicate` | Contacts only | Already researched. Existing result returned. |

> [!WARNING]
>
> If `status` is `error`, verify that your account has sufficient credits and that your API key has the required license permissions before retrying. See [Credits](https://docs.seamless.ai/core-concepts/credits.md).

For HTTP errors such as 401, 422, or 429, see [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md).

## What's next

> [card] [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md)
>
> Start from what you have and what you want back, and find the API that fits.

> [card] [Receive results with webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md)
>
> Skip polling entirely — configure a webhook endpoint and let Seamless push
> completed results to you.

> [card] [Understand identifiers and request flow](https://docs.seamless.ai/core-concepts/understand-identifiers-and-request-flow.md)
>
> Learn which identifiers to save at each step and how the endpoint types fit
> together.

> [card] [Browse the API catalog](https://docs.seamless.ai/api-catalog/overview.md)
>
> Every Seamless.AI API, with what it does, what it costs, and a request you can copy.


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