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

# Troubleshoot Seamless API authentication and requests

> Fix authentication, endpoint sequencing, identifier, and webhook issues with the Seamless API. Each section covers the cause and steps to resolve the failure.

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](https://docs.seamless.ai/authentication/first-request.md) and [Understand identifiers and request flow](https://docs.seamless.ai/core-concepts/understand-identifiers-and-request-flow.md) before continuing here.

## Before you start

* Review [Authenticate and make your first request](https://docs.seamless.ai/authentication/first-request.md) to confirm your authentication setup is correct.
* Review [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md) to confirm you are using the right endpoint family.
* Review [Receive research results with webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md) if your workflow uses async delivery.
* Review [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) for HTTP 401, 403, 422, and 429 responses.

## Common issues

> **You cannot make your first authenticated request**
>
> Determine which authentication method you are using:
>
> * **OAuth** — follow [OAuth](https://docs.seamless.ai/authentication/oauth.md) or call [Get an access token](https://docs.seamless.ai/api-reference/v1/oauth/get-an-access-token.md). Pass `Authorization: Bearer ACCESS_TOKEN` on each request.
> * **API key** — confirm the key from [Settings → Public API → API Key](https://login.seamless.ai/settings/public-api). Pass `Token: YOUR_API_KEY` on each request.
>
> After confirming your credential, retry with [Search companies](https://docs.seamless.ai/api-reference/v1/company-search/search-companies.md) or [Search contacts](https://docs.seamless.ai/api-reference/v1/contact-search/search-contacts.md). 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.

> **You are not sure which endpoint to call next**
>
> The Seamless API follows a fixed sequence. Call endpoints in this order:
>
> 1. **Search** — [Search companies](https://docs.seamless.ai/api-reference/v1/company-search/search-companies.md) or [Search contacts](https://docs.seamless.ai/api-reference/v1/contact-search/search-contacts.md) to find the target record and get a `searchResultId`.
> 2. **Research** — [Research companies](https://docs.seamless.ai/api-reference/v1/company-research/research-companies.md) or [Research contacts](https://docs.seamless.ai/api-reference/v1/contact-research/research-contacts.md) with the `searchResultId` to start enrichment and get a `requestId`.
> 3. **Deliver results** — [webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md), [Poll company research results](https://docs.seamless.ai/api-reference/v1/company-research/poll-company-research.md), or [Poll contact research results](https://docs.seamless.ai/api-reference/v1/contact-research/poll-contact-research.md) with the `requestId` to retrieve the completed result.
>
> If you are unsure which path to take, see [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md).

> **Your workflow stops after research starts**
>
> 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:
>
> * **Webhooks** — use this if your application can receive incoming `POST` requests at a public HTTPS endpoint. See [Receive research results with webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md) for setup instructions.
> * **Polling** — call [Poll company research results](https://docs.seamless.ai/api-reference/v1/company-research/poll-company-research.md) or [Poll contact research results](https://docs.seamless.ai/api-reference/v1/contact-research/poll-contact-research.md) with your `requestId` at a regular interval until `status` returns `done`.
>
> If you have not chosen a result delivery method, the workflow has no path forward and will stall.

> **You are not saving the right identifiers**
>
> 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](https://docs.seamless.ai/core-concepts/understand-identifiers-and-request-flow.md).

> **Your polling workflow is not returning the result you expect**
>
> 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](https://docs.seamless.ai/api-reference/v1/company-research/poll-company-research.md) for company workflows, [Poll contact research results](https://docs.seamless.ai/api-reference/v1/contact-research/poll-contact-research.md) for contact workflows.
> * If the response status is `queued` or `researching`, the request is still in progress. Continue polling at a regular interval until `status` returns `done`, `error`, or (for contacts) `not found` or `duplicate`.
> * A `missing` status means the request ID is not one the server has a record of. For contacts, check the ID; for companies, a request that has not finished yet also polls as `missing`, so keep polling before treating it as lost.
>
> If you prefer not to poll, switch to [webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md) for push delivery.

> **Your webhook endpoint is not receiving events**
>
> Confirm all of the following are true:
>
> * A webhook exists in **Settings → Webhooks** for your Seamless account.
> * The webhook has the right type: **Company Research** for company workflows, or **Contact Research** 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 and returns a `2xx` status.
>
> If all of the above are confirmed and events are still not arriving, poll the research request to confirm it finished, then contact support with the webhook URL and the `requestId`.

> **Your webhook endpoint rejects the request**
>
> 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](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md).

> **You want records already stored in your organization**
>
> Use the org data endpoints to retrieve enriched records without starting a new research request:
>
> * [Get companies](https://docs.seamless.ai/api-reference/v1/org-companies/get-org-companies.md) — returns enriched company records already in your org.
> * [Get contacts](https://docs.seamless.ai/api-reference/v1/org-contacts/get-org-contacts.md) — 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.

> [!NOTE]
>
> **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](https://docs.seamless.ai/authentication/first-request.md)**
>
> Set up authentication and make your first successful API call to the Seamless API.

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

> **[Agent quickstart](https://docs.seamless.ai/api-catalog/agent-quickstart.md)**
>
> Give an AI agent the rules it needs to call the API reliably.

> **[Receive results with webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md)**
>
> Configure an HTTPS endpoint to receive completed research results asynchronously.


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