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). Existing contacts are updated with the supplied fields; new ones are created. Optionally adds every contact in the request to one or more audiences. Results are returned per contact, in submission order — a failed entry does not abort the rest of the request.

Cuerpo de la solicitud

contacts

array of object

obligatorio

Contacts to create or update, matched by email address. Existing contacts are updated with the supplied fields; new ones are created.

Mostrar parámetros secundarios

contacts.email

string

obligatorio

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. 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.

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.

Carga de respuesta

data

array of object

obligatorio

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

Mostrar atributos secundarios

data.email

string

obligatorio

Email address of the contact this entry refers to.

data.status

string

obligatorio

What happened to this contact. A failed entry does not affect the other entries in the request.

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.

Mostrar atributos secundarios

data.error.type

string

obligatorio

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

obligatorio

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