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

# Choose the right workflow

Seamless supports two main integration patterns. In the search-and-research workflow, you search for a company or contact, submit it for enrichment, and receive the completed result — either pushed to your endpoint via webhooks or retrieved on demand by polling. If you already have records in your org, you can skip research and pull existing data directly using the org data endpoints. Choosing the right path depends on whether you need real-time enrichment, asynchronous processing, or bulk retrieval of existing data.

## Recommended paths

<Tabs>
  <Tab title="Company">
    <Steps>
      <Step title="Authenticate">
        Create an API key under [Settings → Public API](/authentication/api-keys), or complete [OAuth](/authentication/oauth). Use `Token` for API keys and `Authorization: Bearer` for OAuth access tokens.
      </Step>

      <Step title="Search for a company">
        Call [Search companies](/searchcompanies) with filters such as `companyName`, `domain`, or `industry`. The response includes a `searchResultId` for each match.

        ```text theme={null}
        POST https://api.seamless.ai/api/client/v1/search/companies
        ```
      </Step>

      <Step title="Request research">
        Pass one or more `searchResultIds` to [Research companies](/researchcompanies). The API queues each record for enrichment and returns a `requestId` per record.

        ```text theme={null}
        POST https://api.seamless.ai/api/client/v1/companies/research
        ```
      </Step>

      <Step title="Receive results">
        Choose how you want to get completed results:

        * **Webhooks** — Configure a webhook endpoint and Seamless pushes results to you as soon as each record is done. See [Receive research results with webhooks](/receive-research-results-with-webhooks).
        * **Polling** — Call [Poll company research results](/pollcompanyresearchresults) with your `requestId` every few seconds until `status` is `done`.

        ```text theme={null}
        GET https://api.seamless.ai/api/client/v1/companies/research/poll?requestIds=YOUR_REQUEST_ID
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Contact">
    <Steps>
      <Step title="Authenticate">
        Create an API key under [Settings → Public API](/authentication/api-keys), or complete [OAuth](/authentication/oauth). Use `Token` for API keys and `Authorization: Bearer` for OAuth access tokens.
      </Step>

      <Step title="Search for a contact">
        Call [Search contacts](/searchcontacts) with filters such as `jobTitle`, `companyName`, or `location`. The response includes a `searchResultId` for each match.

        ```text theme={null}
        POST https://api.seamless.ai/api/client/v1/search/contacts
        ```
      </Step>

      <Step title="Request research">
        Pass one or more `searchResultIds` to [Research contacts](/researchcontacts). The API queues each record for enrichment and returns a `requestId` per record.

        ```text theme={null}
        POST https://api.seamless.ai/api/client/v1/contacts/research
        ```
      </Step>

      <Step title="Receive results">
        Choose how you want to get completed results:

        * **Webhooks** — Configure a webhook endpoint and Seamless pushes results to you as soon as each record is done. See [Receive research results with webhooks](/receive-research-results-with-webhooks).
        * **Polling** — Call [Poll contact research results](/pollcontactsresearchresults) with your `requestId` every few seconds until `status` is `done`.

        ```text theme={null}
        GET https://api.seamless.ai/api/client/v1/contacts/research/poll?requestIds=YOUR_REQUEST_ID
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Retrieve existing org records

If you have already researched companies or contacts and want to retrieve them without starting a new research request, use the org data endpoints directly:

* [Get companies](/getcompanies) — retrieve enriched company records already in your org.
* [Get contacts](/getcontacts) — retrieve enriched contact records already in your org.

<Tip>
  Use the org data endpoints for bulk exports or when syncing Seamless data into a CRM or data warehouse. They return records you've already paid credits to research, so no additional credits are consumed.

  If you already have company domains or contact names from another system, you can skip search and call [Research without search](/research-without-search) to enrich directly.
</Tip>

## Webhooks vs. polling

Both delivery methods give you the same enriched data. The right choice depends on your infrastructure:

|                  | Webhooks                                        | Polling                                 |
| ---------------- | ----------------------------------------------- | --------------------------------------- |
| **How it works** | Seamless pushes results to your HTTPS endpoint  | You call the poll endpoint repeatedly   |
| **Best for**     | Event-driven architectures, real-time pipelines | Scripts, notebooks, simple integrations |
| **Requires**     | A publicly reachable HTTPS endpoint             | Nothing additional                      |
| **Latency**      | Near-instant on completion                      | Depends on your poll interval           |

<Note>
  You can use both methods in the same integration. Webhooks handle the happy path; polling acts as a fallback for records your webhook missed.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="You don't know where to start">
    If you're integrating for the first time, follow the [First Request](/authenticate-and-make-your-first-request) guide. It walks through authentication, a company search, a research submission, and polling for results — end to end — with code samples in curl, Python, and Node.js.

    If you already have `searchResultIds` from a previous search, you can skip to the research step. If you already have `requestIds` from a previous research submission, you can skip directly to polling or check your webhook logs.
  </Accordion>

  <Accordion title="You don't know whether to use webhooks or polling">
    Start with polling. It requires no additional infrastructure — just call the poll endpoint in a loop until `status` is `done`. Once your integration is working, migrate to webhooks if you need lower latency or want to avoid polling overhead.

    To set up webhooks, see [Receive research results with webhooks](/receive-research-results-with-webhooks). You'll need a publicly reachable HTTPS endpoint that can accept `POST` requests from Seamless.
  </Accordion>

  <Accordion title="Your research request returned an 'error' status">
    An `error` poll status means Seamless could not process the record. The most common causes are:

    * **Insufficient credits** — check your credit balance in **Settings → Billing**.
    * **License restrictions** — your API key may not have permission to research this record type. Contact support to review your license.
    * **Invalid searchResultId** — confirm the ID came from a successful search response and hasn't expired.
  </Accordion>

  <Accordion title="You submitted a research request but never received a result">
    If you're using webhooks, verify that your endpoint is publicly reachable and returns a `2xx` status on receipt. Check your webhook delivery logs for failed attempts.

    If you're polling, confirm you're using the correct `requestId` and that you're polling the right endpoint (companies vs. contacts). A `researching` status means the request is still in progress — continue polling.
  </Accordion>
</AccordionGroup>