Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar

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
Autorização
AuthorizationToken Bearer · headerobrigatório

A BillionSend API key (bs_…).

Parâmetros de consulta
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).

padrão: "error"
Valores permitidos:errorskipupsert
Parâmetros de cabeçalho
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.

Valores permitidos:strictpermissive
Corpo da requisição
obrigatórioapplication/json
Array de CreateContactRequest
emailstring<email>obrigatório

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

Mostrar propriedades
Array de object
idstring<uuid>obrigatório
topicsobject[]

Initial per-topic subscription choices

Mostrar propriedades
Array de object
idstring<uuid>obrigatório
subscriptionstringobrigatório
Valores permitidos:opt_inopt_out
Respostas
200

Batch processed

dataobject[]obrigatório

One entry per successful item, in request order

Mostrar propriedades
Array de object
objectstringobrigatório
Valores permitidos:contact
indexintegerobrigatório

Position of the item in the request array

idstring<uuid>obrigatório

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

statusstringobrigatório
Valores permitidos:createdupdatedskipped
countsobjectobrigatório

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

Mostrar propriedades
createdintegerobrigatório
updatedintegerobrigatório
skippedintegerobrigatório
failedintegerobrigatório
errorsobject[]

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

Mostrar propriedades
Array de object
indexintegerobrigatório
statusCodeintegerobrigatório
namestringobrigatório
messagestringobrigatório
401

Missing, malformed, unknown or revoked API key

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
403

Plan limit reached (strict mode)

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
404

Unknown segment or topic (strict mode)

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
409

Contact already exists (strict mode, on_conflict=error)

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
422

Validation error

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
429

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

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
Experimentar
Servidor
Autorização
Parâmetros
Corpoapplication/json
Requisição
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"
      }
    ]
  }
]'
Resposta
{
  "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"
    }
  ]
}

Esta página foi útil?