> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Export Contacts (v3)

> Bulk, incremental export of contacts, with the contacts deleted since the cursor in the same list. Rows are in the order to apply them, so the last row for an ID is that contact's state.

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 you are caught up: keep the cursor you sent and send it again on the next sync. A cursor from [Export Contacts](/api-reference/export-contacts) is accepted, so a sync can move to this endpoint without starting over. Deletions are kept for about six months: a stored cursor whose deletions are more than 179 days old, or whose walk started more than 178 days before it read any, returns `400 cursor_expired`, and you restart without a cursor.

> **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`.



## OpenAPI

````yaml /openapi.json post /v3/exports/contacts
openapi: 3.1.0
info:
  title: Conversion API
  version: 2.0.0
  description: >-
    The Conversion API lets you programmatically manage contacts, track custom
    events, and manage their associated data.
servers:
  - url: https://pub-api.conversion.ai/api
security:
  - apiKey: []
  - apiKeyQuery: []
paths:
  /v3/exports/contacts:
    post:
      summary: Export Contacts (v3)
      description: >-
        Bulk, incremental export of contacts, with the contacts deleted since
        the cursor in the same list. Rows are in the order to apply them, so the
        last row for an ID is that contact's state.


        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 you are caught up: keep the cursor you sent
        and send it again on the next sync. A cursor from [Export
        Contacts](/api-reference/export-contacts) is accepted, so a sync can
        move to this endpoint without starting over. Deletions are kept for
        about six months: a stored cursor whose deletions are more than 179 days
        old, or whose walk started more than 178 days before it read any,
        returns `400 cursor_expired`, and you restart without a cursor.


        > **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`.
      operationId: exportContactsV3
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cursor:
                  type: string
                  description: >-
                    The opaque pagination cursor returned as
                    `pagination.nextCursor` by a previous call to this endpoint
                    or to Export Contacts. Omit (or pass an empty string) on the
                    first call to start from the beginning: every live contact,
                    then every deleted contact Conversion still keeps. An
                    invalid or malformed cursor returns an `invalid_cursor`
                    error.
                  examples:
                    - >-
                      c1.eyJjb250YWN0cyI6ImV5SmpjbVZoZEdWa1FYUWlPaUl5TURJMkxUQXhMVEUxVkRFd09qTXdPakF3V2lKOSIsImRlbGV0aW9ucyI6eyJ1cGRhdGVkQXQiOiIyMDI2LTA1LTMxVDEyOjAwOjAwWiIsInJlY29yZElkIjoiYjJjM2Q0ZTUtZjZhNy04OTAxLWJjZGUtZjIzNDU2Nzg5MDEyIn19
                limit:
                  type: integer
                  minimum: 1
                  maximum: 5000
                  default: 1000
                  description: >-
                    The maximum number of live contacts per page. A page also
                    carries up to this many (at most 1000) deleted or restored
                    contacts. Defaults to 1000. Values are clamped to the range
                    [1, 5000] rather than rejected; values above 5000 return
                    5000 results.
            examples:
              first-page:
                summary: First page
                value:
                  limit: 1000
              next-page:
                summary: Resume from a cursor
                value:
                  cursor: >-
                    c1.eyJjb250YWN0cyI6ImV5SmpjbVZoZEdWa1FYUWlPaUl5TURJMkxUQXhMVEUxVkRFd09qTXdPakF3V2lKOSIsImRlbGV0aW9ucyI6eyJ1cGRhdGVkQXQiOiIyMDI2LTA1LTMxVDEyOjAwOjAwWiIsInJlY29yZElkIjoiYjJjM2Q0ZTUtZjZhNy04OTAxLWJjZGUtZjIzNDU2Nzg5MDEyIn19
                  limit: 1000
      responses:
        '200':
          description: A page of contacts retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - contacts
                    properties:
                      contacts:
                        type: array
                        description: >-
                          The page's contacts, in the order to apply them. Live
                          contacts come first; deleted and restored contacts
                          follow once every live contact has been listed. A live
                          contact has `deleted: false` and every property; a
                          deleted contact has only `id`, `deleted`, and
                          `deletedAt`. A deleted contact that is restored comes
                          back as a live row.
                        items:
                          type: object
                          required:
                            - id
                            - deleted
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: >-
                                The Conversion contact ID. Stable primary key
                                for warehouse upserts.
                            deleted:
                              type: boolean
                              description: '`true` when the contact was deleted.'
                            deletedAt:
                              type: string
                              format: date-time
                              description: >-
                                When the contact was deleted. Present only on a
                                deleted row.
                            sfdcLeadId:
                              type:
                                - string
                                - 'null'
                              description: >-
                                The contact's Salesforce id when its Salesforce
                                object type is Lead; otherwise `null`.
                            sfdcContactId:
                              type:
                                - string
                                - 'null'
                              description: >-
                                The contact's Salesforce id when its Salesforce
                                object type is Contact; otherwise `null`.
                            sfdcAccountId:
                              type:
                                - string
                                - 'null'
                              description: >-
                                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:
                              type: string
                              format: email
                            subscriptionStatus:
                              type: string
                              description: >-
                                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`.
                              examples:
                                - SUBSCRIBED
                            createdAt:
                              type: string
                              format: date-time
                            updatedAt:
                              type: string
                              format: date-time
                            fields:
                              type: object
                              additionalProperties:
                                type: string
                              description: >-
                                Every contact field (variable schema) value,
                                keyed by its common name (e.g. `owner_id`).
                  pagination:
                    type: object
                    required:
                      - nextCursor
                    properties:
                      nextCursor:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Opaque cursor for the next page, or `null` when the
                          export is caught up. On `null`, keep the cursor you
                          sent and send it again on the next sync.
              examples:
                with-more-pages:
                  summary: More pages available
                  value:
                    data:
                      contacts:
                        - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                          deleted: false
                          sfdcLeadId: 00Q5f000001AbCdEAE
                          sfdcContactId: null
                          sfdcAccountId: 0015f00000ACMExAAB
                          email: jane@example.com
                          subscriptionStatus: SUBSCRIBED
                          createdAt: '2026-01-15T10:30:00Z'
                          updatedAt: '2026-06-01T08:15:00Z'
                          fields:
                            first_name: Jane
                            owner_id: 0055f000000AbCdEFG
                    pagination:
                      nextCursor: >-
                        c1.eyJjb250YWN0cyI6ImV5SmpjbVZoZEdWa1FYUWlPaUl5TURJMkxUQTJMVEF4VkRBNE9qRTFPakF3V2lKOSIsImRlbGV0aW9ucyI6eyJ1cGRhdGVkQXQiOiIyMDI2LTA1LTMxVDEyOjAwOjAwWiIsInJlY29yZElkIjoiYjJjM2Q0ZTUtZjZhNy04OTAxLWJjZGUtZjIzNDU2Nzg5MDEyIn19
                live-walk-ends:
                  summary: Live walk ends, deletions follow
                  value:
                    data:
                      contacts:
                        - id: f9e8d7c6-b5a4-3210-fedc-ba9876543210
                          deleted: false
                          sfdcLeadId: null
                          sfdcContactId: null
                          sfdcAccountId: null
                          email: bob@example.com
                          subscriptionStatus: UNSUBSCRIBED
                          createdAt: '2026-02-20T12:00:00Z'
                          updatedAt: '2026-06-02T09:00:00Z'
                          fields: {}
                        - id: c3d4e5f6-a7b8-9012-cdef-345678901234
                          deleted: true
                          deletedAt: '2026-06-01T09:00:00Z'
                    pagination:
                      nextCursor: >-
                        c1.eyJjb250YWN0cyI6ImV5SmpjbVZoZEdWa1FYUWlPaUl5TURJMkxUQTJMVEF4VkRBNE9qRTFPakF3V2lKOSIsImRlbGV0aW9ucyI6eyJ1cGRhdGVkQXQiOiIyMDI2LTA2LTAxVDA5OjAwOjAwWiIsInJlY29yZElkIjoiYzNkNGU1ZjYtYTdiOC05MDEyLWNkZWYtMzQ1Njc4OTAxMjM0In19
                caught-up:
                  summary: Caught up
                  value:
                    data:
                      contacts:
                        - id: f9e8d7c6-b5a4-3210-fedc-ba9876543210
                          deleted: false
                          sfdcLeadId: null
                          sfdcContactId: null
                          sfdcAccountId: null
                          email: bob@example.com
                          subscriptionStatus: UNSUBSCRIBED
                          createdAt: '2026-02-20T12:00:00Z'
                          updatedAt: '2026-06-02T09:00:00Z'
                          fields: {}
                    pagination:
                      nextCursor: null
        '400':
          description: The request was malformed or contained invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid-cursor:
                  summary: Invalid cursor
                  value:
                    error:
                      code: invalid_cursor
                      message: invalid pagination cursor
                cursor-expired:
                  summary: Cursor expired
                  value:
                    error:
                      code: cursor_expired
                      message: >-
                        pagination cursor expired; restart the export without a
                        cursor
                invalid-business:
                  summary: Invalid business
                  value:
                    error:
                      code: invalid_business
                      message: invalid business id
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Missing or invalid API key
                  value:
                    error:
                      code: unauthorized
                      message: API key is required
        '403':
          description: The export API is not enabled for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                export-not-enabled:
                  summary: Export not enabled
                  value:
                    error:
                      code: export_not_enabled
                      message: business is not authorized to use the export API
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal:
                  summary: Internal error
                  value:
                    error:
                      code: internal_error
                      message: failed to list contacts
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: A machine-readable error code.
              examples:
                - invalid_email
            message:
              type: string
              description: A human-readable error description.
              examples:
                - 'invalid email format: not-an-email'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your Conversion API key. Found in **Settings > Integrations** in the
        dashboard. Format: `sk_live_<key_id>_<secret>`.
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: >-
        Your Conversion API key, sent as a query parameter instead of the
        `X-API-Key` header. Prefer the header: URLs can end up in logs and
        browser history.

````

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