Conversion Contacts API

openapi: 3.2.0
info:
  title: Conversion Contacts 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: []
tags:
- name: Contacts
paths:
  /v2/contacts:
    post:
      operationId: upsertContact
      summary: Upsert Contact
      description: Create a new contact or update an existing one. Contacts are identified by `email` or `cnvContactId`. If the contact exists, its fields are updated; if not, a new contact is created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: The contact's email address. At least one of `email` or `cnvContactId` is required. When both are provided, `cnvContactId` identifies the contact and `email` updates the contact's email address.
                  examples:
                  - jane@example.com
                cnvContactId:
                  type: string
                  format: uuid
                  description: The Conversion contact ID. Use this to identify an existing contact by its internal ID instead of email. At least one of `email` or `cnvContactId` is required.
                  examples:
                  - a1b2c3d4-e5f6-7890-abcd-ef1234567890
                subscriptionStatus:
                  $ref: '#/components/schemas/SubscriptionStatus'
                fields:
                  $ref: '#/components/schemas/ContactFields'
                companyFields:
                  $ref: '#/components/schemas/CompanyFields'
                updateOnly:
                  type: boolean
                  default: false
                  description: When `true`, restricts the operation to updates only. Returns a `contact_not_found` error if no existing contact matches the provided identifier.
                syncToCRM:
                  type: boolean
                  default: false
                  description: When `true`, syncs the contact to the connected CRM (e.g., Salesforce) if the contact does not already have an external CRM record.
                preserveExistingFields:
                  type: boolean
                  default: false
                  description: When `true`, prevents overwriting existing non-empty field values. New values are only written to fields that are currently empty or unset. Useful for enrichment workflows.
            examples:
              create-with-fields:
                summary: Create contact with fields
                value:
                  email: jane@example.com
                  subscriptionStatus: SUBSCRIBED
                  fields:
                    first_name: Jane
                    last_name: Smith
                    job_title: VP of Marketing
                  companyFields:
                    company_name: Acme Corp
              update-by-id:
                summary: Update by contact ID
                value:
                  cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fields:
                    job_title: Director of Marketing
              enrich:
                summary: Enrich without overwriting
                value:
                  email: jane@example.com
                  preserveExistingFields: true
                  fields:
                    first_name: Jane
                    last_name: Smith
                    phone: +1-555-0100
      responses:
        '200':
          description: Contact upserted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - cnvContactId
                    - contactCreated
                    properties:
                      cnvContactId:
                        type: string
                        format: uuid
                        description: The Conversion contact ID of the created or updated contact.
                      contactCreated:
                        type: boolean
                        description: '`true` if a new contact was created, `false` if an existing contact was updated.'
              examples:
                created:
                  summary: Contact created
                  value:
                    data:
                      cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      contactCreated: true
                updated:
                  summary: Contact updated
                  value:
                    data:
                      cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      contactCreated: false
        '400':
          description: The request was malformed or contained invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing-identifier:
                  summary: Missing identifier
                  value:
                    error:
                      code: missing_identifier
                      message: either 'email' or 'cnvContactId' is required
                invalid-email:
                  summary: Invalid email
                  value:
                    error:
                      code: invalid_email
                      message: 'invalid email format: not-an-email'
                invalid-field:
                  summary: Unknown field
                  value:
                    error:
                      code: invalid_field
                      message: field 'nonexistent_key' does not exist
                invalid-subscription-status:
                  summary: Invalid subscription status
                  value:
                    error:
                      code: invalid_subscription_status
                      message: invalid subscription status value
        '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
        '404':
          description: Contact not found (when `updateOnly` is true).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-found:
                  summary: Contact not found
                  value:
                    error:
                      code: contact_not_found
                      message: no contact found with the provided identifier
        '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 upsert contact
      tags:
      - Contacts
    get:
      operationId: getContact
      summary: Get Contact
      description: 'Fetch a single contact by `email` or `cnvContactId`. Provide exactly one identifier; `cnvContactId` takes precedence when both are provided.


        When looking up by `email`, the most recently updated contact with that email address is returned.


        > **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`.'
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
          format: email
        description: The contact's email address. When multiple contacts share the same email, the most recently updated contact is returned.
        examples:
          example:
            value: jane@example.com
      - name: cnvContactId
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: The Conversion contact ID.
        examples:
          example:
            value: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Contact retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - contact
                    properties:
                      contact:
                        $ref: '#/components/schemas/Contact'
              examples:
                found:
                  summary: Contact found
                  value:
                    data:
                      contact:
                        cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        email: jane@example.com
                        userId: user_12345
                        subscriptionStatus: SUBSCRIBED
                        fields:
                          first_name: Jane
                          last_name: Smith
                          job_title: VP of Marketing
                        createdAt: '2026-01-10T08:00:00Z'
                        updatedAt: '2026-02-03T14:22:05Z'
        '400':
          description: The request was malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing-identifier:
                  summary: Missing identifier
                  value:
                    error:
                      code: missing_identifier
                      message: at least one of email or cnvContactId is required
                invalid-email:
                  summary: Invalid email
                  value:
                    error:
                      code: invalid_email
                      message: 'invalid email format: not-an-email'
        '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: This endpoint is not enabled for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-enabled:
                  summary: Endpoint not enabled
                  value:
                    error:
                      code: export_not_enabled
                      message: business is not authorized to use this endpoint
        '404':
          description: The contact was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                contact-not-found:
                  summary: Contact not found
                  value:
                    error:
                      code: contact_not_found
                      message: no contact found matching the provided identifier
        '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 get contact
      tags:
      - Contacts
  /v2/contacts/batch:
    post:
      operationId: batchUpsertContacts
      summary: Batch Upsert Contacts
      description: Create or update up to 1,000 contacts in a single request, with a result for each contact. Optionally pass `audienceId` to add successfully upserted contacts to a static audience.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contacts
              properties:
                contacts:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  description: An array of contact objects to upsert.
                  items:
                    type: object
                    description: A single contact to upsert. Provide at least one of `email`, `cnvContactId`, or `userId`. Matching prioritizes `cnvContactId`, then `userId`, then email.
                    properties:
                      email:
                        type: string
                        format: email
                        description: The contact's email address. Required when creating a new contact; updates the email when matching an existing contact by ID.
                        examples:
                        - jane@example.com
                      cnvContactId:
                        type: string
                        format: uuid
                        description: The Conversion contact ID. Takes precedence over `userId` and email when identifying an existing contact.
                        examples:
                        - a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      userId:
                        type: string
                        description: Your stable contact identifier, scoped to your workspace. If unmatched, email can match a contact with no user ID and assign this ID; a different existing user ID creates a separate contact unless `updateOnly` is true. Blank values are ignored and do not clear the ID.
                        examples:
                        - user_12345
                      subscriptionStatus:
                        $ref: '#/components/schemas/SubscriptionStatus'
                      fields:
                        $ref: '#/components/schemas/ContactFields'
                      companyFields:
                        $ref: '#/components/schemas/CompanyFields'
                updateOnly:
                  type: boolean
                  default: false
                  description: When `true`, restricts all operations to updates only. Contacts that are not found will be returned with a `contact_not_found` error in their result item.
                syncToCRM:
                  type: boolean
                  default: false
                  description: When `true`, syncs upserted contacts to the connected CRM (e.g., Salesforce) if they do not already have an external CRM record.
                preserveExistingFields:
                  type: boolean
                  default: false
                  description: When `true`, prevents overwriting existing non-empty field values for all contacts in the batch. New values are only written to fields that are currently empty or unset.
                audienceId:
                  type: string
                  format: uuid
                  description: Optional Conversion static audience ID. Add successfully upserted contacts to this audience. The audience must belong to the API key workspace.
            examples:
              basic:
                summary: Basic batch upsert
                value:
                  contacts:
                  - email: jane@example.com
                    subscriptionStatus: SUBSCRIBED
                    fields:
                      first_name: Jane
                      last_name: Smith
                  - email: bob@example.com
                    subscriptionStatus: SUBSCRIBED
                    fields:
                      first_name: Bob
                      last_name: Jones
                    companyFields:
                      company_name: Acme Corp
              enrichment:
                summary: Enrichment mode
                value:
                  preserveExistingFields: true
                  contacts:
                  - email: jane@example.com
                    fields:
                      first_name: Jane
                      phone: +1-555-0100
              audience:
                summary: Upsert contacts and add audience membership
                value:
                  audienceId: 8e112222-3333-4444-8555-666677778888
                  contacts:
                  - email: jane@example.com
                    fields:
                      first_name: Jane
      responses:
        '200':
          description: Batch processed. Check data.failed and each result for contact or audience failures. An invalid audience is reported for each contact before any writes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - processed
                    - succeeded
                    - failed
                    - results
                    properties:
                      processed:
                        type: integer
                        description: The total number of contacts in the batch.
                      succeeded:
                        type: integer
                        description: The number of contacts with all requested operations completed.
                      failed:
                        type: integer
                        description: The number of contacts that failed.
                      results:
                        type: array
                        description: An array of result objects in the same order as the input `contacts` array.
                        items:
                          type: object
                          required:
                          - success
                          properties:
                            success:
                              type: boolean
                              description: True if the contact was upserted and, when audienceId is supplied, added to that audience.
                            cnvContactId:
                              type: string
                              format: uuid
                              description: The saved contact ID, including when the audience add fails.
                            contactCreated:
                              type: boolean
                              description: True if a new contact was created. Retained if the audience add fails.
                            error:
                              type: string
                              description: A machine-readable error code. Present on failure.
                            message:
                              type: string
                              description: A human-readable error description. Present on failure.
              examples:
                all-success:
                  summary: All contacts upserted
                  value:
                    data:
                      processed: 2
                      succeeded: 2
                      failed: 0
                      results:
                      - success: true
                        cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        contactCreated: true
                      - success: true
                        cnvContactId: f9e8d7c6-b5a4-3210-fedc-ba9876543210
                        contactCreated: false
                partial-failure:
                  summary: Partial failure
                  value:
                    data:
                      processed: 2
                      succeeded: 1
                      failed: 1
                      results:
                      - success: true
                        cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        contactCreated: true
                      - success: false
                        error: invalid_email
                        message: 'invalid email format: not-an-email'
                audience-add-failure:
                  summary: Contact saved but audience add failed
                  value:
                    data:
                      processed: 1
                      succeeded: 0
                      failed: 1
                      results:
                      - success: false
                        cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        contactCreated: true
                        error: audience_add_failed
                        message: contact saved, but audience membership could not be confirmed
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid-request:
                  summary: Invalid request body
                  value:
                    error:
                      code: invalid_request
                      message: request validation failed
        '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
        '500':
          description: An internal error prevented batch processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal:
                  summary: Internal error
                  value:
                    error:
                      code: internal_error
                      message: failed to upsert contacts
        '403':
          description: The API key lacks contact write permissions or edit access to the audience.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - 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'
    Contact:
      type: object
      required:
      - cnvContactId
      - fields
      - createdAt
      - updatedAt
      properties:
        cnvContactId:
          type: string
          format: uuid
          description: The Conversion contact ID.
        email:
          type:
          - string
          - 'null'
          format: email
          description: The contact's email address, or `null` when not set.
        userId:
          type:
          - string
          - 'null'
          description: An external user identifier for the contact, or `null` when not set.
        subscriptionStatus:
          $ref: '#/components/schemas/SubscriptionStatus'
        fields:
          $ref: '#/components/schemas/ContactFields'
        createdAt:
          type: string
          format: date-time
          description: When the contact was created.
        updatedAt:
          type: string
          format: date-time
          description: When the contact was last updated.
    CompanyFields:
      type: object
      additionalProperties: {}
      description: A map of company field keys to values for the contact's associated company.
      examples:
      - company_name: Acme Corp
        industry: Technology
    ContactFields:
      type: object
      additionalProperties: {}
      description: A map of contact field keys to values. Keys must match existing field definitions in your Conversion account.
      examples:
      - first_name: Jane
        last_name: Smith
        job_title: VP of Marketing
    SubscriptionStatus:
      type: string
      enum:
      - SUBSCRIBED
      - UNSUBSCRIBED
      - NO_STATUS
      description: The contact's email subscription status. System-managed statuses (`BOUNCED`, `COMPLAINED`, etc.) cannot be set through the API.
  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.'