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

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

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

**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);
```

**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`.

**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);
```

**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 [Rate limits and credits](https://docs.seamless.ai/core-concepts/rate-limits-and-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

> **[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.

> **[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.

> **[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.

> **[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.