> ## 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](https://docs.seamless.ai/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://docs.seamless.ai/api-catalog/mcp.md) | `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. 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 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](https://docs.seamless.ai/authentication/api-keys.md) and [OAuth](https://docs.seamless.ai/authentication/oauth.md).

## 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](https://docs.seamless.ai/api-catalog/contact-search.md) |
| An ICP (industry, size, tech...) | List of companies | `POST /search/companies` with [filters](https://docs.seamless.ai/api-catalog/company-search.md) |
| Records your org already researched | Full data, free | `GET /contacts` or `GET /companies` |

The full grid is in [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md).

## 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](https://docs.seamless.ai/workflows/receive-research-results-with-webhooks.md).

**4. Read**

When `status` is `done`, the `contact` object holds emails, phones, location, and job history. See the [Data dictionary](https://docs.seamless.ai/api-catalog/data-dictionary.md).

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 company | 1 credit per record |
| Research a contact | By default 1 for email, 5 for phone, 6 for both |
| Poll, location lookup, My Contact Data, My Company Data, `/oauth/me`, `/credits` | Free |

Every authenticated response carries `X-PublicAPI-Credits` (credits left). `GET /v2/credits` returns balances by category. Exact rules: [Credits](https://docs.seamless.ai/core-concepts/credits.md).

## 6. Stay inside the limits

* Limits are per endpoint and shared across your organization. Read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` on every response rather than assuming a number.
* `limit` on search is capped at 500 rows. Research takes up to 500 records per call in total across `searchResultIds` and `contacts`.

## 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` `missingApiAccess` | Stop and tell the user to enable Public API access. |
| `429` | Wait until `X-RateLimit-Reset`, then retry. |
| `500` | Retry with exponential backoff (1s, 2s, 4s, 8s), then stop. |

Every code is in [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md).

## 8. Rules that save credits

* Resolve city names with the free [Location Lookup](https://docs.seamless.ai/api-catalog/location-lookup.md) 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](https://docs.seamless.ai/llms.txt) |
| Full docs text | [https://docs.seamless.ai/llms-full.txt](https://docs.seamless.ai/llms-full.txt) |
| OpenAPI v1 | `https://docs.seamless.ai/openapi.json` |
| OpenAPI v2 | `https://docs.seamless.ai/v2-openapi.json` |
| MCP server | `https://mcp.seamless.ai/mcp` |
| Every API in one table | [API catalog index](https://docs.seamless.ai/api-catalog/overview.md#for-ai-agents) |


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