AI agents: read this page first. It holds everything needed to call Seamless.AI correctly. The full docs index is at /llms.txt, and any page is available as Markdown by adding
.md to its URL.1. Choose how to connect
v2 includes every v1 endpoint, so one base URL covers everything. The same API key works on both. Public API v2 is in beta: every v2 endpoint returns
403 (noFeatureAccess) until Seamless enables v2 for your organization.
2. Authenticate
Send the API key in theToken header on every request:
Authorization: Bearer <access_token> instead. A 401 means the key is missing or wrong. See API keys and OAuth.
3. Pick the endpoint from what you have
The full grid is in Choose an API.
4. Follow the search, research, poll loop
Search results are previews without emails or phones. Research unlocks them.1
Search
POST /search/contacts returns rows with a searchResultId and supplementalData.nextToken for the next page.2
Research
POST /contacts/research with up to 500 records in total across searchResultIds and contacts returns 202 and one entry in requestIds per record.3
Poll
GET /contacts/research/poll?requestIds=ID1,ID2 every 2 to 5 seconds until no status is queued or researching. Or receive results by webhook.4
Read
When
status is done, the contact object holds emails, phones, location, and job history. See the Data dictionary.5. Know the costs before you call
Every authenticated response carries
X-PublicAPI-Credits (credits left). GET /v2/credits returns balances by category. Exact rules: Credits.
6. Stay inside the limits
- Limits are per endpoint and shared across your organization. Read
X-RateLimit-Limit,X-RateLimit-Remaining, andX-RateLimit-Reseton every response rather than assuming a number. limiton search is capped at 500 rows. Research takes up to 500 records per call in total acrosssearchResultIdsandcontacts.
7. Handle errors
Every code is in Error codes.
8. Rules that save credits
- Resolve city names with the free Location Lookup before searching. A misspelled location returns nothing.
- A poll status of
duplicatemeans the record is already in your org. Read it free fromGET /contacts. - Ask the user before research calls that will spend more than a few credits.
- Page with
nextToken, notpage.