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

> Learn which identifier belongs to which step of the search, research, and result-delivery sequence, and how to avoid passing the wrong ID to the wrong endpoint.

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.

## Request flow

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

**Search** finds targets. Call [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) 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](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). 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](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. 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](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md).

**Org data endpoints** retrieve records already stored in your organization. Call [Get companies](https://docs.seamless.ai/api-reference/v1/org-companies/get-org-companies.md) or [Get contacts](https://docs.seamless.ai/api-reference/v1/org-contacts/get-org-contacts.md) 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

**Company**

**1. Search companies**

Call [Search companies](https://docs.seamless.ai/api-reference/v1/company-search/search-companies.md) with filters such as `companyName`, `companyDomain`, or `industry`.

**2. Save the search result ID**

Identify the matching record in the response and save its `searchResultId`.

**3. Research companies**

Pass your `searchResultId` to [Research companies](https://docs.seamless.ai/api-reference/v1/company-research/research-companies.md). The API queues the record and returns a `requestId`.

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

**5. 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](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md).
* **Polling** — Call [Poll company research results](https://docs.seamless.ai/api-reference/v1/company-research/poll-company-research.md) with your `requestId` until `status` is `done`.

**Contact**

**1. Search contacts**

Call [Search contacts](https://docs.seamless.ai/api-reference/v1/contact-search/search-contacts.md) with filters such as `jobTitle`, `companyName`, or `locations`.

**2. Save the search result ID**

Identify the matching record in the response and save its `searchResultId`.

**3. Research contacts**

Pass your `searchResultId` to [Research contacts](https://docs.seamless.ai/api-reference/v1/contact-research/research-contacts.md). The API queues the record and returns a `requestId`.

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

**5. 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](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md).
* **Polling** — Call [Poll contact research results](https://docs.seamless.ai/api-reference/v1/contact-research/poll-contact-research.md) with your `requestId` until `status` is `done`.

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

## Troubleshooting

> **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](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). Use it to start a research request.
> * **`requestId`** — produced by [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). 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`.

> **You are calling the wrong endpoint type**
>
> Each endpoint type has a specific role and accepts specific inputs:
>
> * **Search** — finds targets. Use [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 produce a `searchResultId`.
> * **Research** — starts enrichment. Use [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 a `searchResultId` to produce a `requestId`.
> * **Polling or webhooks** — retrieves completed results. Use [Poll company research results](https://docs.seamless.ai/api-reference/v1/company-research/poll-company-research.md), [Poll contact research results](https://docs.seamless.ai/api-reference/v1/contact-research/poll-contact-research.md), or [webhooks](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md) with a `requestId`.
> * **Org data** — retrieves stored records. Use [Get companies](https://docs.seamless.ai/api-reference/v1/org-companies/get-org-companies.md) or [Get contacts](https://docs.seamless.ai/api-reference/v1/org-contacts/get-org-contacts.md) 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 endpoint, see [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md).


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