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.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.
Recommended paths
- Company
- Contact
Authenticate
Create an API key under Settings → Public API, or complete OAuth. Use
Token for API keys and Authorization: Bearer for OAuth access tokens.Search for a company
Call Search companies with filters such as
companyName, domain, or industry. The response includes a searchResultId for each match.Request research
Pass one or more
searchResultIds to Research companies. The API queues each record for enrichment and returns a requestId per record.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.
- Polling — Call Poll company research results with your
requestIdevery few seconds untilstatusisdone.
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 — retrieve enriched company records already in your org.
- Get contacts — retrieve enriched contact records already in your org.
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 |
You can use both methods in the same integration. Webhooks handle the happy path; polling acts as a fallback for records your webhook missed.
Troubleshooting
You don't know where to start
You don't know where to start
If you’re integrating for the first time, follow the 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.You don't know whether to use webhooks or polling
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. You’ll need a publicly reachable HTTPS endpoint that can accept POST requests from Seamless.Your research request returned an 'error' status
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.
You submitted a research request but never received a result
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.