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.

Most integration issues fall into a small set of categories: authentication not working, the wrong endpoint called at the wrong step, identifiers not saved or mixed up, and result delivery not configured. This page covers each failure pattern with specific steps to resolve it. If you are setting up the integration for the first time, read Authenticate and make your first request and Choose the right workflow before continuing here.

​
Before you start

​
Common issues

Determine which authentication method you are using:After confirming your credential, retry with Search companies or Search contacts. If the request still fails, confirm you are passing the correct access token or API key and that it has not expired or been revoked.
The Seamless API follows a fixed sequence. Call endpoints in this order:
  1. Search — Search companies or Search contacts to find the target record and get a searchResultId.
  2. Research — Research companies or Research contacts with the searchResultId to start enrichment and get a requestId.
  3. Deliver results — webhooks, Poll company research results, or Poll contact research results with the requestId to retrieve the completed result.
If you are unsure which path to take, see Choose the right workflow.
The research endpoint is asynchronous — it returns a requestId immediately but does not wait for enrichment to finish. You must configure a result delivery method to retrieve the completed record:If you have not chosen a result delivery method, the workflow has no path forward and will stall.
Two separate identifiers exist in this workflow, and each is used at a different step:
  • searchResultId — produced by the search endpoint. Save it immediately after the search response. Pass it to the research endpoint to initiate enrichment.
  • requestId — produced by the research endpoint. Save it immediately after the research response. Use it for polling or to match against incoming webhook payloads.
Do not overwrite the searchResultId with the requestId. Keep both stored separately until your workflow is complete. For more detail, see Understand identifiers and request flow.
Check the following:
  • Confirm the requestId you are passing to the polling endpoint came from the research response for this request — not from a search response or a different research request.
  • Confirm you are calling the correct polling endpoint for your workflow: Poll company research results for company workflows, Poll contact research results for contact workflows.
  • If the response status is researching, the request is still in progress. Continue polling at a regular interval until status returns done, missing, error, or (for contacts) duplicate.
If you prefer not to poll, switch to webhooks for push delivery.
Confirm all of the following are true:
  • A webhook exists in Settings → Webhooks for your Seamless account.
  • The webhook is configured with the correct event type: company-researched for company workflows, or contact-researched for contact workflows.
  • Your endpoint is publicly reachable over HTTPS. Local addresses such as localhost cannot receive events from the platform.
  • Your endpoint accepts POST requests.
If all of the above are confirmed and events are still not arriving, check the webhook delivery logs in Settings → Webhooks for failed delivery attempts.
A rejected request typically means secret validation failed or the payload was not parsed correctly:
  • Secret validation — read the x-seamless-webhook-secret header from the incoming request and compare it to the shared secret configured in Settings → Webhooks. The values must match exactly, including case and whitespace. Confirm the secret is set correctly in your deployed environment variables.
  • Payload parsing — confirm your application parses the request body as JSON before reading any fields. If you are using Express, ensure express.json() middleware runs before your route handler.
  • Response code — your endpoint must return a 2xx status code after accepting the event. Any other status causes the platform to treat the delivery as failed and may trigger a retry.
For receiver code examples and validation guidance, see Receive research results with webhooks.
Use the org data endpoints to retrieve enriched records without starting a new research request:
  • Get companies — returns enriched company records already in your org.
  • Get contacts — returns enriched contact records already in your org.
These endpoints do not require a searchResultId or requestId. No additional credits are consumed when retrieving existing records.
AI agent guidance: store the access token or API key, searchResultId, and requestId as separate named values and carry them through all steps. Do not repeat search or research when the agent already has the identifier needed for the next step. Choose one result delivery method per request. If the agent cannot determine which identifier to use or which endpoint to call next, stop and escalate to the caller rather than retrying.

​
Next steps

Authenticate and make your first request

Set up authentication and make your first successful API call to the Seamless API.

End-to-end company workflow

Walk through the full company search, research, and result-retrieval flow with code examples.

End-to-end contact workflow

Walk through the full contact search, research, and result-retrieval flow with code examples.

Understand identifiers and request flow

Learn which identifiers to save at each step and how the endpoint types fit together.

Build a deterministic agent workflow

Build a repeatable AI agent workflow with branching rules, stop conditions, and error handling.

Receive results with webhooks

Configure an HTTPS endpoint to receive completed research results asynchronously.