> ## 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](/authenticate-and-make-your-first-request) and [Choose the right workflow](/choose-the-right-workflow) before continuing here.

## Before you start

* Review [Authenticate and make your first request](/authenticate-and-make-your-first-request) to confirm your authentication setup is correct.
* Review [Choose the right workflow](/choose-the-right-workflow) to confirm you are using the right endpoint family and delivery method.
* Review [Receive research results with webhooks](/receive-research-results-with-webhooks) if your workflow uses async delivery.
* Review [API HTTP status codes](/api-http-status-codes) for HTTP 401, 403, 422, and 429 responses.

## Common issues

<AccordionGroup>
  <Accordion title="You cannot make your first authenticated request">
    Determine which authentication method you are using:

    * **OAuth** — follow [OAuth](/authentication/oauth) or call [Get an access token](/reference/getaccesstoken). 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](/searchcompanies) or [Search contacts](/searchcontacts). 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.
  </Accordion>

  <Accordion title="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](/searchcompanies) or [Search contacts](/searchcontacts) to find the target record and get a `searchResultId`.
    2. **Research** — [Research companies](/researchcompanies) or [Research contacts](/researchcontacts) with the `searchResultId` to start enrichment and get a `requestId`.
    3. **Deliver results** — [webhooks](/receive-research-results-with-webhooks), [Poll company research results](/pollcompanyresearchresults), or [Poll contact research results](/pollcontactsresearchresults) with the `requestId` to retrieve the completed result.

    If you are unsure which path to take, see [Choose the right workflow](/choose-the-right-workflow).
  </Accordion>

  <Accordion title="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](/receive-research-results-with-webhooks) for setup instructions.
    * **Polling** — call [Poll company research results](/pollcompanyresearchresults) or [Poll contact research results](/pollcontactsresearchresults) 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.
  </Accordion>

  <Accordion title="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](/understand-identifiers-and-request-flow).
  </Accordion>

  <Accordion title="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](/pollcompanyresearchresults) for company workflows, [Poll contact research results](/pollcontactsresearchresults) 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](/receive-research-results-with-webhooks) for push delivery.
  </Accordion>

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

  <Accordion title="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](/receive-research-results-with-webhooks).
  </Accordion>

  <Accordion title="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](/getcompanies) — returns enriched company records already in your org.
    * [Get contacts](/getcontacts) — 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.
  </Accordion>
</AccordionGroup>

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

## Next steps

<CardGroup cols={2}>
  <Card title="Authenticate and make your first request" icon="key" href="/authenticate-and-make-your-first-request">
    Set up authentication and make your first successful API call to the Seamless API.
  </Card>

  <Card title="End-to-end company workflow" icon="building" href="/end-to-end-company-workflow">
    Walk through the full company search, research, and result-retrieval flow with code examples.
  </Card>

  <Card title="End-to-end contact workflow" icon="user" href="/end-to-end-contact-workflow">
    Walk through the full contact search, research, and result-retrieval flow with code examples.
  </Card>

  <Card title="Understand identifiers and request flow" icon="id-card" href="/understand-identifiers-and-request-flow">
    Learn which identifiers to save at each step and how the endpoint types fit together.
  </Card>

  <Card title="Build a deterministic agent workflow" icon="robot" href="/build-a-deterministic-agent-workflow">
    Build a repeatable AI agent workflow with branching rules, stop conditions, and error handling.
  </Card>

  <Card title="Receive results with webhooks" icon="webhook" href="/receive-research-results-with-webhooks">
    Configure an HTTPS endpoint to receive completed research results asynchronously.
  </Card>
</CardGroup>