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.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.
Request flow
Each endpoint type in the Seamless API has a distinct role. They are not interchangeable. Search finds targets. Call Search companies or Search contacts with filters to identify records you want to enrich. Each matching record in the response carries asearchResultId. Save this identifier — it is the input to the next stage.
Research starts an enrichment request. Pass a searchResultId to Research companies or Research contacts. 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 or Poll contact research results 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.
Org data endpoints retrieve records already stored in your organization. Call Get companies or Get contacts 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
- Contact
Search companies
Call Search companies with filters such as
companyName, domain, or industry.Research companies
Pass your
searchResultId to Research companies. The API queues the record and returns a requestId.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.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.
- Polling — Call Poll company research results with your
requestIduntilstatusisdone.
Troubleshooting
You do not know which ID to use
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 or Search contacts. Use it to start a research request.requestId— produced by Research companies or Research contacts. Use it to track the request and retrieve the result via polling or webhooks.
searchResultId. If it came from a research response, it is a requestId.You are calling the wrong endpoint type
You are calling the wrong endpoint type
Each endpoint type has a specific role and accepts specific inputs:
- Search — finds targets. Use Search companies or Search contacts to produce a
searchResultId. - Research — starts enrichment. Use Research companies or Research contacts with a
searchResultIdto produce arequestId. - Polling or webhooks — retrieves completed results. Use Poll company research results, Poll contact research results, or webhooks with a
requestId. - Org data — retrieves stored records. Use Get companies or Get contacts to pull records already in your organization without starting a new research request.