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

# My Contact Data API

> Export every contact your organization has researched, for CRM and warehouse sync, and manage their list membership. Free.

> [!NOTE]
>
> **Endpoints** `GET /contacts` · `POST /contacts` (v2) · **Credits** free ·
> **Versions** v1, v2

## Introduction

Every contact your organization researches, through the Seamless app, Chrome extension, API, or MCP, is saved to your org. The My Contact Data API reads those records back with full emails, phones, and job details, without spending credits. Use it to sync Seamless data into your CRM, warehouse, or product, and to manage which lists each contact belongs to.

The `GET` endpoint is on v1 and v2; the `POST` list-membership endpoint is v2 only. Public API v2 is in beta: v2 endpoints return `403` (`noFeatureAccess`) until Seamless enables v2 for your organization.

> [!TIP]
>
> If a research poll returns `duplicate`, the contact is already in your org.
> Read it here instead of paying to research it again.

## AI agent prompt

```text theme={null}
Read https://docs.seamless.ai/api-catalog/my-contact-data. Using SEAMLESS_API_KEY, write a nightly job that calls
GET https://api.seamless.ai/api/client/v1/contacts with startDate/endDate covering the last 24 hours,
pages through every result, and upserts each record into my database keyed on contactId.
```

## Authentication

Send your API key in the `Token` header, or `Authorization: Bearer <token>` with [OAuth](https://docs.seamless.ai/authentication/oauth.md). Create a key under [Settings → Public API](https://docs.seamless.ai/authentication/api-keys.md).

## Example

```bash Export (incremental) theme={null}
curl "https://api.seamless.ai/api/client/v1/contacts?startDate=2026-10-19T00:00:00Z&endDate=2026-10-20T00:00:00Z&page=1&limit=100" \
  -H "Token: $SEAMLESS_API_KEY"
```

```bash Add to a list (v2) theme={null}
curl -X POST https://api.seamless.ai/api/client/v2/contacts \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": [48213377], "listIds": [123], "listAction": "add"}'
```

For Python, JavaScript, and other languages, see [Get Org Contacts](https://docs.seamless.ai/api-reference/v1/org-contacts/get-org-contacts.md) in the API reference.

## Reference

### `GET /contacts`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `page` | integer | No | The page number to retrieve. Default `1`. |
| `limit` | integer | No | The number of results per page. Default `500`. |
| `startDate` | string | Yes | An ISO8601 date time string that defines the start date of the lookback period to return results from. |
| `endDate` | string | Yes | An ISO8601 date time string that defines the end date of the lookback period to return results from. |

### `POST /contacts` (v2)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `contactIds` | integer\[] | Yes | IDs of the saved contacts to update. Up to 500 values. |
| `listIds` | integer\[] | No | IDs of the contact lists to apply. The lists must already belong to you; an unknown ID fails the request. May be empty only with `listAction` `replace`, which clears every list off the contacts. Up to 50 values. |
| `listAction` | string | No | How `listIds` is applied. `add` keeps the lists the contacts are already in, `remove` drops only the supplied lists, and `replace` makes the supplied lists their complete set of lists. Default `add`. |

**Allowed values for `listAction`:** `add`, `remove`, `replace`

## Response

`data` is an array of full contact records with the same fields as [Contact Research](https://docs.seamless.ai/api-catalog/contact-enrichment.md): `contactId`, names, `jobTitle`, emails with validation, phones, location, company firmographics, and job history. See the [Data dictionary](https://docs.seamless.ai/api-catalog/data-dictionary.md).

## Errors

| Status | Meaning |
| - | - |
| `401` | Missing or invalid API key |
| `422` | `missingApiAccess`: no active Public API license |
| `429` | Rate limit reached |

## Related

* [My Company Data](https://docs.seamless.ai/api-catalog/my-company-data.md)
* [Use case: Sync researched contacts to CRM](https://docs.seamless.ai/use-cases/sync-researched-contacts-to-crm.md)
* [API reference: Get org contacts](https://docs.seamless.ai/api-reference/v1/org-contacts/get-org-contacts.md)


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