Create or Update Contacts in Bulk
Page Tools
/contacts/bulkUpserts up to 100 contacts in one request. Items are processed independently: one failing item never aborts the batch — inspect per-item results. Duplicate phone numbers within a batch are rejected as a whole-request 400.
x-api-key.AuthenticationRequest Body
application/json- No additional properties
1-100 contacts; duplicate phone numbers in one batch are rejected
- 1–100 items
Show item detailsHide item details for body.contacts
Each item
E.164 (+1234567890) or digits-only (1234567890) format
- 1–255 characters
- 1–255 characters
- Up to 255 characters
- Format: email
- 1–255 characters
- 1–255 characters
Date of birth in YYYY-MM-DD format. Must be a valid date in the past; null clears the value.
- Pattern: ^\d{4}-\d{2}-\d{2}$
- 1–255 characters
- 1–255 characters
Full replace on updates; usable in segment rules
- Up to 100 items
Show item detailsHide item details for body.contacts[].tags
Each item
- 1–100 characters
- 1–100 characters
Map of up to 50 fields. Values may be strings (up to 1,000 characters), numbers, booleans, arrays of up to 100 strings, or null. Nested objects are not accepted. Keys must match ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$; __proto__, constructor, and prototype are reserved. A null value deletes that key on update.
- Up to 50 properties
Show child fieldsHide child fields for body.contacts[].customFields
Show child fieldsHide child fields for body.contacts[].customFields.[key]
One or more variants may apply.
- Up to 1000 characters
Setting OPTED_IN attests that you collected the contact's marketing consent. OPTED_IN is rejected (422) when the contact previously opted out (e.g. texted STOP); OPTED_OUT is always accepted. Contacts default to UNKNOWN, and campaigns only send to OPTED_IN contacts.
"OPTED_IN""OPTED_OUT"Responses
Per-item results with summary counts