Create or update contacts in bulk

POST

/v1/contacts/batch

curl -X POST "https://us1.platform.bird.com/v1/contacts/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "email": "alice@acme.com",
        "first_name": "Alice",
        "last_name": "Anderson"
      },
      {
        "email": "bob@acme.com",
        "first_name": "Bob",
        "last_name": "Baker"
      }
    ],
    "audience_ids": [
      "adn_01krdgeqcxet5s7t44vh8rt9mg"
    ]
  }'

Creates or updates up to 1,000 contacts in one request, matched by email address (trimmed and lowercased before matching). A new address creates a contact; an existing one is updated with the fields that entry supplies, and omitted fields keep their stored values. Optionally adds every contact in the request to up to 10 audiences.

Each entry succeeds or fails on its own: the response lists one result per contact in submission order (created, updated, or failed with the reason), and a failed entry does not abort the rest. If the request itself is invalid, for example when an entry in audience_ids does not exist, the whole request fails with a validation error and no contacts are written.

Corps de la requête

contacts

array of object

obligatoire

Contacts to create or update, matched by email address. Existing contacts are updated with the fields each entry supplies; omitted fields keep their stored values, so an entry can set fields but never clear them. New addresses create contacts.

Afficher les paramètres enfants

contacts.email

string

obligatoire

The contact's email address. Trimmed and lowercased before it is stored and checked for uniqueness. Unique within the workspace.

contacts.first_name

string

The contact's first name.

contacts.last_name

string

The contact's last name.

contacts.external_id

string

Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.

contacts.data

object

Custom property values for this contact. Each key must be a property created via the contact properties API, and each value must be a string, number, or boolean matching the property's declared type (strings up to 500 characters); a null value is ignored. Unregistered or archived keys are rejected with a validation error. Total size is capped at 2 KB serialized.

audience_ids

array of string

Audiences every contact in this request is added to. Contacts that are already members are left in place. Every listed audience must exist, or the whole request fails with a validation error and nothing is written.

data_mode

string

How a supplied data object is applied to an existing contact. merge (the default) merges the supplied keys onto the contact's stored custom values, and a key with a null value deletes that one key. replace overwrites the whole stored data map with the supplied one. In both modes a contact that omits data keeps its stored values unchanged, so an import that touches one attribute never wipes the others.

Possible values: merge, replace

Contenu de la réponse

data

array of object

obligatoire

One entry per contact in the request, in submission order.

Afficher les attributs enfants

data.email

string

obligatoire

Email address this entry refers to, in the normalized (trimmed and lowercased) form it was matched and stored as.

data.status

string

obligatoire

What happened to this contact. created means a new contact was created for the address; updated means an existing contact with the address was updated; failed means the entry was rejected and error explains why. A failed entry does not affect the other entries in the request.

Possible values: created, updated, failed

data.contact_id

string

ID of the created or updated contact. Absent when the entry failed.

data.error

object

Why this entry failed. Absent for successful entries.

Afficher les attributs enfants

data.error.type

string

obligatoire

Machine-readable error category for this entry, such as validation_error or conflict_error, in the same vocabulary as the top-level error type. New categories may be added over time, so treat unrecognized values as a generic failure.

data.error.message

string

obligatoire

Human-readable explanation of why this entry failed.

curl -X POST "https://us1.platform.bird.com/v1/contacts/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "email": "alice@acme.com",
        "first_name": "Alice",
        "last_name": "Anderson"
      },
      {
        "email": "bob@acme.com",
        "first_name": "Bob",
        "last_name": "Baker"
      }
    ],
    "audience_ids": [
      "adn_01krdgeqcxet5s7t44vh8rt9mg"
    ]
  }'