---
title: "Export Contacts"
method: POST
path: "/v2/exports/contacts"
---

# Export Contacts

`POST /v2/exports/contacts`

## Request

- Base URL: `https://pub-api.conversion.ai/api`
- URL: `https://pub-api.conversion.ai/api/v2/exports/contacts`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

Bulk, incremental export of contacts, ordered by `updatedAt` ascending. Each contact's fields are flattened under `fields`, keyed by their label.

Results are paginated with an opaque cursor returned as `pagination.nextCursor`. Pass it back as `cursor` to fetch the next page; a `null` cursor means there are no more results. Persist the last non-null cursor between syncs to resume. Passing the stored cursor on a later call yields contacts created or updated since.

> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.

## Request body

- object
  - `cursor` string: The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit (or pass an empty string) on the first call to start from the beginning. An invalid or malformed cursor returns an `invalid_cursor` error.
  - `limit` integer: The maximum number of contacts to return per page. Defaults to 1000. Values are clamped to the range [1, 5000] rather than rejected; values above 5000 return 5000 results.

## Response `200`

A page of contacts retrieved successfully.

- object
  - `data` object
    - `contacts` object[], required: The current page of exported contacts.
      - `id` string, uuid, required: The Conversion contact ID. Stable primary key for warehouse upserts.
      - `sfdcLeadId` string, nullable: The contact's Salesforce id when its Salesforce object type is Lead; otherwise `null`.
      - `sfdcContactId` string, nullable: The contact's Salesforce id when its Salesforce object type is Contact; otherwise `null`.
      - `sfdcAccountId` string, nullable: The Salesforce Account id of the contact's linked company, or `null` when the contact has no company or it isn't synced to Salesforce.
      - `email` string, email, required
      - `subscriptionStatus` string, required: The contact's email subscription status. In addition to `SUBSCRIBED`, `UNSUBSCRIBED`, and `NO_STATUS`, exported values may include system-managed statuses such as `BOUNCED` or `COMPLAINED`.
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `fields` object, required: Every contact field (variable schema) value, keyed by its common name (e.g. `owner_id`).
  - `pagination` object
    - `nextCursor` string, nullable, required: Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist.

## Other responses

- `400`: The request was malformed or contained invalid data.
- `401`: Authentication failed.
- `403`: The export API is not enabled for this account.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)