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.
Request Payload
contacts
array of object
required
Contacts to create or update, matched by email address. Existing contacts are updated with the supplied fields; new ones are created.
Show child parameters
contacts.email
string
required
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.
Response Payload
data
array of object
required
One entry per contact in the request, in submission order.
Show child attributes
data.email
string
required
Email address of the contact this entry refers to.
data.status
string
required
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.
Show child attributes
data.error.type
string
required
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
required
Human-readable explanation of why this entry failed.