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/batchAuthorizationBearer token · headerrequiredA 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>requiredBare 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
Show propertiesHide properties
objectidstring<uuid>requiredtopicsobject[]Initial per-topic subscription choices
Show propertiesHide properties
objectidstring<uuid>requiredsubscriptionstringrequiredopt_inopt_outBatch processed
dataobject[]requiredOne entry per successful item, in request order
Show propertiesHide properties
objectobjectstringrequiredcontactindexintegerrequiredPosition of the item in the request array
idstring<uuid>requiredThe contact's id (the existing one for skipped/updated)
statusstringrequiredcreatedupdatedskippedcountsobjectrequiredPer-status totals over the request items; they sum to the request length
Show propertiesHide properties
createdintegerrequiredupdatedintegerrequiredskippedintegerrequiredfailedintegerrequirederrorsobject[]Permissive mode only: the failed items by request index, each with the statusCode and name strict mode would answer for it
Show propertiesHide properties
objectindexintegerrequiredstatusCodeintegerrequirednamestringrequiredmessagestringrequiredMissing, malformed, unknown or revoked API key
statusCodenumberrequirednamestringrequiredmessagestringrequiredPlan limit reached (strict mode)
statusCodenumberrequirednamestringrequiredmessagestringrequiredUnknown segment or topic (strict mode)
statusCodenumberrequirednamestringrequiredmessagestringrequiredContact already exists (strict mode, on_conflict=error)
statusCodenumberrequirednamestringrequiredmessagestringrequiredValidation error
statusCodenumberrequirednamestringrequiredmessagestringrequiredOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberrequirednamestringrequiredmessagestringrequired