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/batchAuthorizationToken Bearer · headerobligatorioA 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>obligatorioBare 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 propiedadesOcultar propiedades
objectidstring<uuid>obligatoriotopicsobject[]Initial per-topic subscription choices
Mostrar propiedadesOcultar propiedades
objectidstring<uuid>obligatoriosubscriptionstringobligatorioopt_inopt_outBatch processed
dataobject[]obligatorioOne entry per successful item, in request order
Mostrar propiedadesOcultar propiedades
objectobjectstringobligatoriocontactindexintegerobligatorioPosition of the item in the request array
idstring<uuid>obligatorioThe contact's id (the existing one for skipped/updated)
statusstringobligatoriocreatedupdatedskippedcountsobjectobligatorioPer-status totals over the request items; they sum to the request length
Mostrar propiedadesOcultar propiedades
createdintegerobligatorioupdatedintegerobligatorioskippedintegerobligatoriofailedintegerobligatorioerrorsobject[]Permissive mode only: the failed items by request index, each with the statusCode and name strict mode would answer for it
Mostrar propiedadesOcultar propiedades
objectindexintegerobligatoriostatusCodeintegerobligatorionamestringobligatoriomessagestringobligatorioMissing, malformed, unknown or revoked API key
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioPlan limit reached (strict mode)
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioUnknown segment or topic (strict mode)
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioContact already exists (strict mode, on_conflict=error)
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioValidation error
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorio