Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa

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

POST/contacts/batch
Autorización
AuthorizationToken Bearer · headerobligatorio

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

predeterminado: "error"
Valores permitidos:errorskipupsert
Parámetros de encabezado
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
Cuerpo de la solicitud
obligatorioapplication/json
Array de CreateContactRequest
emailstring<email>obligatorio

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 propiedades
Array de object
idstring<uuid>obligatorio
topicsobject[]

Initial per-topic subscription choices

Mostrar propiedades
Array de object
idstring<uuid>obligatorio
subscriptionstringobligatorio
Valores permitidos:opt_inopt_out
Respuestas
200

Batch processed

dataobject[]obligatorio

One entry per successful item, in request order

Mostrar propiedades
Array de object
objectstringobligatorio
Valores permitidos:contact
indexintegerobligatorio

Position of the item in the request array

idstring<uuid>obligatorio

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

statusstringobligatorio
Valores permitidos:createdupdatedskipped
countsobjectobligatorio

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

Mostrar propiedades
createdintegerobligatorio
updatedintegerobligatorio
skippedintegerobligatorio
failedintegerobligatorio
errorsobject[]

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

Mostrar propiedades
Array de object
indexintegerobligatorio
statusCodeintegerobligatorio
namestringobligatorio
messagestringobligatorio
401

Missing, malformed, unknown or revoked API key

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
403

Plan limit reached (strict mode)

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
404

Unknown segment or topic (strict mode)

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
409

Contact already exists (strict mode, on_conflict=error)

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
422

Validation error

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
429

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

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
Pruébalo
Servidor
Autorización
Parámetros
Cuerpoapplication/json
Solicitud
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"
      }
    ]
  }
]'
Respuesta
{
  "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"
    }
  ]
}

¿Te ha resultado útil esta página?