Skip to main content

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.

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:
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.
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
  }'
Example response:
{
  "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.
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.
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"]
  }'
Both endpoints return HTTP 202 Accepted with the same JSON body:
{
  "success": true,
  "requestIds": ["YOUR_REQUEST_ID"]
}
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.
curl -X GET "https://api.seamless.ai/api/client/v1/companies/research/poll?requestIds=YOUR_REQUEST_ID" \
  -H "Token: $SEAMLESS_API_KEY"
When research is still running, the response looks like this:
{
  "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:
{
  "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

StatusApplies toMeaning
researchingBothStill processing. Poll again in a few seconds.
doneBothResearch complete. Full record is available.
missingBothNo result found for the record.
errorBothCould not process. Check credits and license.
duplicateContacts onlyAlready researched. Existing result returned.
If status is error, verify that your account has sufficient research credits and that your API key has the required license permissions before retrying.
For HTTP errors such as 401, 422, or 429, see API HTTP status codes.

​
What’s next

Choose a workflow

Compare search, research, webhooks, polling, and org data endpoints to find the right path for your use case.

Receive results with webhooks

Skip polling entirely — configure a webhook endpoint and let Seamless push completed results to you.

End-to-end company workflow

A complete walkthrough of the company search, research, and retrieval flow.

End-to-end contact workflow

A complete walkthrough of the contact search, research, and retrieval flow.