Create contacts in bulk
Creates up to 1000 contacts in one request. Each item is a CreateContactRequest. on_conflict decides what happens to an email that already belongs to a contact — error (default), skip, or upsert. An upsert updates first_name/last_name only when provided, merges properties (provided keys overwrite), adds segments and upserts topics. unsubscribed: true opts the contact out; unsubscribed: false on an already unsubscribed contact is ignored — a batch never re-subscribes anyone, that stays an explicit PATCH /contacts/{id}. The x-batch-validation header picks strict (default, all-or-nothing) or permissive (valid subset written, failures listed in errors).
/contacts/batchAuthorizationBearer-Token · headererforderlichA BillionSend API key (bs_…).
on_conflictstringWhat to do with an item whose email (case-insensitive) already belongs to a contact: error fails the item, skip leaves the contact untouched and reports its id, upsert merges the item into it. Also decides how an email repeated inside the batch is handled: error fails the later occurrence, skip keeps the first, upsert collapses them into one write (later scalar fields win, associations are unioned).
errorskipupsertx-batch-validationstringstrict (default): any invalid item rejects the whole batch with that item's status and a contacts.{index}: message prefix, writing nothing. permissive: invalid items are listed in errors and the valid subset is written.
strictpermissiveapplication/jsonCreateContactRequestemailstring<email>erforderlichBare email address (no display name); unique per team
first_namestringFirst name
last_namestringLast name
unsubscribedbooleanGlobal opt-out from all marketing sends
propertiesobjectFlat map of custom properties (string or number values)
segmentsobject[]Segments to add the contact to on creation
Eigenschaften anzeigenEigenschaften ausblenden
objectidstring<uuid>erforderlichtopicsobject[]Initial per-topic subscription choices
Eigenschaften anzeigenEigenschaften ausblenden
objectidstring<uuid>erforderlichsubscriptionstringerforderlichopt_inopt_outBatch processed
dataobject[]erforderlichOne entry per successful item, in request order
Eigenschaften anzeigenEigenschaften ausblenden
objectobjectstringerforderlichcontactindexintegererforderlichPosition of the item in the request array
idstring<uuid>erforderlichThe contact's id (the existing one for skipped/updated)
statusstringerforderlichcreatedupdatedskippedcountsobjecterforderlichPer-status totals over the request items; they sum to the request length
Eigenschaften anzeigenEigenschaften ausblenden
createdintegererforderlichupdatedintegererforderlichskippedintegererforderlichfailedintegererforderlicherrorsobject[]Permissive mode only: the failed items by request index, each with the statusCode and name strict mode would answer for it
Eigenschaften anzeigenEigenschaften ausblenden
objectindexintegererforderlichstatusCodeintegererforderlichnamestringerforderlichmessagestringerforderlichMissing, malformed, unknown or revoked API key
statusCodenumbererforderlichnamestringerforderlichmessagestringerforderlichPlan limit reached (strict mode)
statusCodenumbererforderlichnamestringerforderlichmessagestringerforderlichUnknown segment or topic (strict mode)
statusCodenumbererforderlichnamestringerforderlichmessagestringerforderlichContact already exists (strict mode, on_conflict=error)
statusCodenumbererforderlichnamestringerforderlichmessagestringerforderlichValidation error
statusCodenumbererforderlichnamestringerforderlichmessagestringerforderlichOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumbererforderlichnamestringerforderlichmessagestringerforderlich