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

# Understand identifiers and request flow

Every Seamless API workflow passes two identifiers through a fixed sequence of endpoint types — search, research, and result delivery. Understanding which identifier belongs to which step, and why, prevent common integration errors: passing the wrong ID to the wrong endpoint, or starting a later step before the previous one has produced its output.

```mermaid theme={null}
flowchart LR
  S[Search] -->|searchResultId| R[Research]
  R -->|requestId| P[Polling]
  R -->|requestId| W[Webhook POST]
  O[Org data GET] -.->|no research IDs| O
```

## Request flow

Each endpoint type in the Seamless API has a distinct role. They are not interchangeable.

**Search** finds targets. Call [Search companies](/searchcompanies) or [Search contacts](/searchcontacts) with filters to identify records you want to enrich. Each matching record in the response carries a `searchResultId`. Save this identifier — it is the input to the next stage.

**Research** starts an enrichment request. Pass a `searchResultId` to [Research companies](/researchcompanies) or [Research contacts](/researchcontacts). The API queues the record for enrichment and returns a `requestId`. Save this identifier — it is how you track the request through to completion.

**Polling** checks request status. Call [Poll company research results](/pollcompanyresearchresults) or [Poll contact research results](/pollcontactsresearchresults) with your `requestId` at a regular interval. Continue polling until `status` returns `done`.

**Webhooks** deliver completed results asynchronously. When research finishes, the platform sends a `POST` request to your configured endpoint. No polling required. See [Receive research results with webhooks](/receive-research-results-with-webhooks).

**Org data endpoints** retrieve records already stored in your organization. Call [Get companies](/getcompanies) or [Get contacts](/getcontacts) to pull enriched records without starting a new research request. These endpoints do not accept a `searchResultId` or `requestId` — they are for retrieval, not enrichment.

## Keep the right identifier at each step

| Step     | Identifier to save | Why you need it                                                                       |
| -------- | ------------------ | ------------------------------------------------------------------------------------- |
| Search   | `searchResultId`   | Pass to the research endpoint to identify which record to enrich                      |
| Research | `requestId`        | Pass to the polling endpoint or match against webhook payloads to retrieve the result |
| Polling  | `requestId`        | Required for every poll call until the request reaches a terminal status              |

## Recommended request flow

<Tabs>
  <Tab title="Company">
    <Steps>
      <Step title="Search companies">
        Call [Search companies](/searchcompanies) with filters such as `companyName`, `domain`, or `industry`.
      </Step>

      <Step title="Save the search result ID">
        Identify the matching record in the response and save its `searchResultId`.
      </Step>

      <Step title="Research companies">
        Pass your `searchResultId` to [Research companies](/researchcompanies). The API queues the record and returns a `requestId`.
      </Step>

      <Step title="Save the request ID">
        Save the `requestId` from the research response. Do not overwrite or discard the `searchResultId` — keep both until your workflow is complete.
      </Step>

      <Step title="Choose a result delivery method">
        Retrieve the completed result using one of the following:

        * **Webhooks** — Seamless pushes the result to your endpoint. See [Receive research results with webhooks](/receive-research-results-with-webhooks).
        * **Polling** — Call [Poll company research results](/pollcompanyresearchresults) with your `requestId` until `status` is `done`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Contact">
    <Steps>
      <Step title="Search contacts">
        Call [Search contacts](/searchcontacts) with filters such as `jobTitle`, `companyName`, or `location`.
      </Step>

      <Step title="Save the search result ID">
        Identify the matching record in the response and save its `searchResultId`.
      </Step>

      <Step title="Research contacts">
        Pass your `searchResultId` to [Research contacts](/researchcontacts). The API queues the record and returns a `requestId`.
      </Step>

      <Step title="Save the request ID">
        Save the `requestId` from the research response. Do not overwrite or discard the `searchResultId` — keep both until your workflow is complete.
      </Step>

      <Step title="Choose a result delivery method">
        Retrieve the completed result using one of the following:

        * **Webhooks** — Seamless pushes the result to your endpoint. See [Receive research results with webhooks](/receive-research-results-with-webhooks).
        * **Polling** — Call [Poll contact research results](/pollcontactsresearchresults) with your `requestId` until `status` is `done`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Store `searchResultId` and `requestId` as separate named values. Do not overwrite the search result ID with the request ID — they are different identifiers used at different steps. Do not start research until you have confirmed the correct `searchResultId` from the search response. After research starts, use only the `requestId` for polling and workflow tracking.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="You do not know which ID to use">
    Two identifiers exist in this workflow, and each belongs to a specific step:

    * **`searchResultId`** — produced by [Search companies](/searchcompanies) or [Search contacts](/searchcontacts). Use it to start a research request.
    * **`requestId`** — produced by [Research companies](/researchcompanies) or [Research contacts](/researchcontacts). Use it to track the request and retrieve the result via polling or webhooks.

    If you are unsure which identifier you have, check where it came from. If it came from a search response, it is a `searchResultId`. If it came from a research response, it is a `requestId`.
  </Accordion>

  <Accordion title="You are calling the wrong endpoint type">
    Each endpoint type has a specific role and accepts specific inputs:

    * **Search** — finds targets. Use [Search companies](/searchcompanies) or [Search contacts](/searchcontacts) to produce a `searchResultId`.
    * **Research** — starts enrichment. Use [Research companies](/researchcompanies) or [Research contacts](/researchcontacts) with a `searchResultId` to produce a `requestId`.
    * **Polling or webhooks** — retrieves completed results. Use [Poll company research results](/pollcompanyresearchresults), [Poll contact research results](/pollcontactsresearchresults), or [webhooks](/receive-research-results-with-webhooks) with a `requestId`.
    * **Org data** — retrieves stored records. Use [Get companies](/getcompanies) or [Get contacts](/getcontacts) to pull records already in your organization without starting a new research request.

    If your call is failing, confirm you are using the correct endpoint type for the current step. For help choosing the right workflow, see [Choose the right workflow](/choose-the-right-workflow).
  </Accordion>
</AccordionGroup>