Create 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/batchAuthorizationToken Bearer · headerobrigatórioA 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>obrigatórioBare 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
Mostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatóriotopicsobject[]Initial per-topic subscription choices
Mostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatóriosubscriptionstringobrigatórioopt_inopt_outBatch processed
dataobject[]obrigatórioOne entry per successful item, in request order
Mostrar propriedadesOcultar propriedades
objectobjectstringobrigatóriocontactindexintegerobrigatórioPosition of the item in the request array
idstring<uuid>obrigatórioThe contact's id (the existing one for skipped/updated)
statusstringobrigatóriocreatedupdatedskippedcountsobjectobrigatórioPer-status totals over the request items; they sum to the request length
Mostrar propriedadesOcultar propriedades
createdintegerobrigatórioupdatedintegerobrigatórioskippedintegerobrigatóriofailedintegerobrigatórioerrorsobject[]Permissive mode only: the failed items by request index, each with the statusCode and name strict mode would answer for it
Mostrar propriedadesOcultar propriedades
objectindexintegerobrigatóriostatusCodeintegerobrigatórionamestringobrigatóriomessagestringobrigatórioMissing, malformed, unknown or revoked API key
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioPlan limit reached (strict mode)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioUnknown segment or topic (strict mode)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioContact already exists (strict mode, on_conflict=error)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioValidation error
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatório