COconversion

Batch Upsert Contacts

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.

post/v2/contacts/batch

Request

  • Base URL
    https://pub-api.conversion.ai/api
  • Auth
    • API key in header X-API-Key
    • or API key in query parameter api_key

Request body

updateOnlyboolean

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.

syncToCRMboolean

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

preserveExistingFieldsboolean

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.

audienceIdstring uuid

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

Example request

{
  "contacts": [
    {
      "email": "jane@example.com",
      "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "userId": "user_12345",
      "fields": {
        "first_name": "Jane",
        "last_name": "Smith",
        "job_title": "VP of Marketing"
      },
      "companyFields": {
        "company_name": "Acme Corp",
        "industry": "Technology"
      }
    }
  ]
}

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.

Changes

No recorded changes to this operation across all 1 revision of this API.