Skip to content
Esc
↑↓navigate↵open⌘Jpreview

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).

POST/contacts/batch
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Query parameters
on_conflictstring

What 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).

default: "error"
Allowed:errorskipupsert
Header parameters
x-batch-validationstring

strict (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.

Allowed:strictpermissive
Request body
requiredapplication/json
Array of CreateContactRequest
emailstring<email>required

Bare email address (no display name); unique per team

first_namestring

First name

last_namestring

Last name

unsubscribedboolean

Global opt-out from all marketing sends

propertiesobject

Flat map of custom properties (string or number values)

segmentsobject[]

Segments to add the contact to on creation

Show properties
Array of object
idstring<uuid>required
topicsobject[]

Initial per-topic subscription choices

Show properties
Array of object
idstring<uuid>required
subscriptionstringrequired
Allowed:opt_inopt_out
Responses
200

Batch processed

dataobject[]required

One entry per successful item, in request order

Show properties
Array of object
objectstringrequired
Allowed:contact
indexintegerrequired

Position of the item in the request array

idstring<uuid>required

The contact's id (the existing one for skipped/updated)

statusstringrequired
Allowed:createdupdatedskipped
countsobjectrequired

Per-status totals over the request items; they sum to the request length

Show properties
createdintegerrequired
updatedintegerrequired
skippedintegerrequired
failedintegerrequired
errorsobject[]

Permissive mode only: the failed items by request index, each with the statusCode and name strict mode would answer for it

Show properties
Array of object
indexintegerrequired
statusCodeintegerrequired
namestringrequired
messagestringrequired
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Plan limit reached (strict mode)

statusCodenumberrequired
namestringrequired
messagestringrequired
404

Unknown segment or topic (strict mode)

statusCodenumberrequired
namestringrequired
messagestringrequired
409

Contact already exists (strict mode, on_conflict=error)

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/contacts/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "email": "user@example.com",
    "first_name": "string",
    "last_name": "string",
    "unsubscribed": true,
    "properties": {
      "property1": null,
      "property2": null
    },
    "segments": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      }
    ],
    "topics": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "subscription": "opt_in"
      }
    ]
  }
]'
Response
{
  "data": [
    {
      "object": "contact",
      "index": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "status": "created"
    }
  ],
  "counts": {
    "created": 0,
    "updated": 0,
    "skipped": 0,
    "failed": 0
  },
  "errors": [
    {
      "index": 0,
      "statusCode": 0,
      "name": "string",
      "message": "string"
    }
  ]
}

Was this page helpful?