Batch Upsert Contacts - Conversion Docs

curl --request POST \
  --url https://pub-api.conversion.ai/api/v2/contacts/batch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "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
      }
    ]
  }
}

POST

/

v2

/

contacts

/

batch

curl --request POST \
  --url https://pub-api.conversion.ai/api/v2/contacts/batch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "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
      }
    ]
  }
}

Authorizations

X-API-Key

string

header

required

Your Conversion API key. Found in Settings > Integrations in the dashboard. Format: sk_live_<key_id>_<secret>.

Body

application/json

contacts

object[]

required

An array of contact objects to upsert.

Required array length: 1 - 1000 elements

Show child attributes

updateOnly

boolean

default:false

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

boolean

default:false

When true, syncs upserted contacts to the connected CRM (e.g., Salesforce) if they do not already have an external CRM record.

preserveExistingFields

boolean

default:false

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

string<uuid>

Optional Conversion static audience ID. Add successfully upserted contacts to this audience. The audience must belong to the API key workspace.

Response

Batch processed. Check data.failed and each result for contact or audience failures. An invalid audience is reported for each contact before any writes.

data

object

Show child attributes