> ## 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`.
</Note>

<Steps>
  <Step title="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.

    <Tabs>
      <Tab title="Company">
        <CodeGroup>
          ```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);
          ```
        </CodeGroup>

        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>

      <Tab title="Contact">
        <CodeGroup>
          ```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);
          ```
        </CodeGroup>

        The response structure mirrors the company search. Save the `searchResultId` for the contact you want to enrich.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Company">
        <CodeGroup>
          ```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);
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Contact">
        <CodeGroup>
          ```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);
          ```
        </CodeGroup>
      </Tab>
    </Tabs>

    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.
    </Note>
  </Step>

  <Step title="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`.

    <Tabs>
      <Tab title="Company">
        <CodeGroup>
          ```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);
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Contact">
        <CodeGroup>
          ```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);
          ```
        </CodeGroup>
      </Tab>
    </Tabs>

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

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

    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",
          "message": "",
          "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"
          },
          "additionalData": {}
        }
      ]
    }
    ```

    ### Poll status values

    | Status        | Applies to    | Meaning                                        |
    | ------------- | ------------- | ---------------------------------------------- |
    | `researching` | Both          | Still processing. Poll again in a few seconds. |
    | `done`        | Both          | Research complete. Full record is available.   |
    | `missing`     | Both          | No result found for the record.                |
    | `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 research credits and that your API key has the required license permissions before retrying.
    </Warning>

    For HTTP errors such as 401, 422, or 429, see [API HTTP status codes](/api-http-status-codes).
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="Choose a workflow" icon="map" href="/choose-the-right-workflow">
    Compare search, research, webhooks, polling, and org data endpoints to find the right path for your use case.
  </Card>

  <Card title="Receive results with webhooks" icon="webhook" href="/receive-research-results-with-webhooks">
    Skip polling entirely — configure a webhook endpoint and let Seamless push completed results to you.
  </Card>

  <Card title="End-to-end company workflow" icon="building" href="/end-to-end-company-workflow">
    A complete walkthrough of the company search, research, and retrieval flow.
  </Card>

  <Card title="End-to-end contact workflow" icon="user" href="/end-to-end-contact-workflow">
    A complete walkthrough of the contact search, research, and retrieval flow.
  </Card>
</CardGroup>