Skip to main content
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": {
    "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
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.

Response

Batch processed. Check each result item for individual outcomes.

data
object