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

# Agent quickstart

> Everything an AI agent needs to call the Seamless.AI API correctly in one page: access method, auth, which endpoint to use, the search-research-poll loop, costs, limits, errors, and recipes.

> [!NOTE]
>
> **AI agents: read this page first.** It holds everything needed to call Seamless.AI correctly. The full docs index is at [/llms.txt](/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](/api-catalog/mcp) | `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:

```bash theme={null}
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](/authentication/api-keys) and [OAuth](/authentication/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](/api-catalog/contact-search) |
| An ICP (industry, size, tech...) | List of companies | `POST /search/companies` with [filters](/api-catalog/company-search) |
| Records your org already researched | Full data, free | `GET /contacts` or `GET /companies` |

The full grid is in [Choose an API](/api-catalog/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 `searchResultIds` 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](/receive-research-results-with-webhooks).

**4. Read**

When `status` is `done`, the `contact` object holds emails, phones, location, and job history. See the [Data dictionary](/api-catalog/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](/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](/api-catalog/error-codes).

## 8. Rules that save credits

* Resolve city names with the free [Location Lookup](/api-catalog/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

```bash Enrich one email theme={null}
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]>
```

```bash Find VPs at an account theme={null}
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}'
```

```bash Domain to company profile theme={null}
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](/llms.txt) |
| Full docs text | [https://docs.seamless.ai/llms-full.txt](/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](/api-catalog/overview#for-ai-agents) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.