Agent quickstart

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

If your client…	Use	Endpoint
Supports MCP (Claude, ChatGPT, Cursor, VS Code, Claude Code)	MCP server	`https://mcp.seamless.ai/mcp`
Makes HTTP requests (scripts, backends, no-code tools)	REST API	`https://api.seamless.ai/api/client/v1`
Needs engagement or reverse lookup (lists, campaigns, email, phone or email search)	REST API v2	`https://api.seamless.ai/api/client/v2`

v2 includes every v1 endpoint, so one base URL covers everything. The same API key works on both.

2. Authenticate

Send the API key in the Token header on every request:

curl https://api.seamless.ai/api/client/v1/oauth/me -H "Token: $SEAMLESS_API_KEY"

OAuth apps send 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

You have	You want	Call
Email	Person with phones and job	`POST /contacts/research` with `contacts[].email`
LinkedIn URL	Person with emails and phones	`POST /contacts/research` with `contacts[].liProfileUrl`
Name and company	Person with emails and phones	`POST /contacts/research` with `contactName` + `companyName` or `domain`
Phone number	Who it belongs to	`POST /v2/search/contacts` with `phoneNumber`
Company name	Website domain	`POST /search/companies` with `companyName`, `limit: 1`
Domain	Company profile	`POST /companies/research` with `companies[].domain`
A persona (title, seniority, location…)	List of people	`POST /search/contacts` with filters
An ICP (industry, size, tech…)	List of companies	`POST /search/companies` with filters
Records your org already researched	Full data, free	`GET /contacts` or `GET /companies`

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.

POST /search/contacts returns rows with a searchResultId and supplementalData.nextToken for the next page.

Research

POST /contacts/research with up to 500 searchResultIds returns 202 and one entry in requestIds per record.

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.

Read

When status is done, the contact object holds emails, phones, location, and job history. See the Data dictionary.

If you already have an email, LinkedIn URL, or name and company, skip search and go straight to research.

5. Know the costs before you call

Call	Cost
Search contacts or companies	Charged per results returned. Empty pages are free.
Research a contact or company	1 credit per record
Poll, location lookup, My Contact Data, My Company Data, `/oauth/me`, `/credits`	Free

Every response carries X-PublicAPI-Credits (credits left). GET /v2/credits returns balances by category. Exact rules: Rate limits and credits.

6. Stay inside the limits

60 requests per minute per endpoint, shared across your organization.
Read X-RateLimit-Remaining and X-RateLimit-Reset on every response.
limit on search is capped at 500 rows. Research takes up to 500 records per call.

7. Handle errors

Status	Do this
`401` / `403`	Fix credentials. Don’t retry.
`422` `insufficientCredits`	Lower `limit` or batch size, or stop and tell the user.
`422` `missingLicense`	Stop and tell the user to enable Public API access.
`429`	Wait until `X-RateLimit-Reset`, then retry.
`500`	Retry with backoff, up to 5 times.

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 duplicate means the record is already in your org. Read it free from GET /contacts.
Ask the user before research calls that will spend more than a few credits.
Page with nextToken, not page.

Recipes

curl -X POST https://api.seamless.ai/api/client/v1/contacts/research \
  -H "Token: $SEAMLESS_API_KEY" -H "Content-Type: application/json" \
  -d '{"contacts": [{"email": "jane.doe@acme.com"}]}'
# then: GET /contacts/research/poll?requestIds=<requestIds[0]>

curl -X POST https://api.seamless.ai/api/client/v1/search/contacts \
  -H "Token: $SEAMLESS_API_KEY" -H "Content-Type: application/json" \
  -d '{"companyDomain": ["acme.com"], "seniority": ["VP", "C-Level"], "limit": 25}'

curl -X POST https://api.seamless.ai/api/client/v1/companies/research \
  -H "Token: $SEAMLESS_API_KEY" -H "Content-Type: application/json" \
  -d '{"companies": [{"domain": "acme.com"}]}'
# then: GET /companies/research/poll?requestIds=<requestIds[0]>

Machine-readable resources

Resource	URL
Docs index	https://docs.seamless.ai/llms.txt
Full docs text	https://docs.seamless.ai/llms-full.txt
OpenAPI v1	`https://gist.githubusercontent.com/JustinAlia/6ff38a671f5f79895444b77c57f3afff/raw/openapi.json`
OpenAPI v2	`https://gist.githubusercontent.com/JustinAlia/6ff38a671f5f79895444b77c57f3afff/raw/v2-openapi.json`
MCP server	`https://mcp.seamless.ai/mcp`
Every API in one table	API catalog index

Catalog

Start here

Identity resolution

Search

Contact Search filters

Company Search filters

Research

My data

Platform

Coming soon

1. Choose how to connect

2. Authenticate

3. Pick the endpoint from what you have

4. Follow the search, research, poll loop

5. Know the costs before you call

6. Stay inside the limits

7. Handle errors

8. Rules that save credits

Recipes

Machine-readable resources

​1. Choose how to connect

​2. Authenticate

​3. Pick the endpoint from what you have

​4. Follow the search, research, poll loop

​5. Know the costs before you call

​6. Stay inside the limits

​7. Handle errors

​8. Rules that save credits

​Recipes

​Machine-readable resources

1. Choose how to connect

2. Authenticate

3. Pick the endpoint from what you have

4. Follow the search, research, poll loop

5. Know the costs before you call

6. Stay inside the limits

7. Handle errors

8. Rules that save credits

Recipes

Machine-readable resources