Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu

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
Autorisation
AuthorizationJeton Bearer · headerrequis

A BillionSend API key (bs_…).

Paramètres de requête
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).

par défaut : "error"
Valeurs autorisées :errorskipupsert
Paramètres d'en-tête
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.

Valeurs autorisées :strictpermissive
Corps de la requête
requisapplication/json
Tableau de CreateContactRequest
emailstring<email>requis

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

Afficher les propriétés
Tableau de object
idstring<uuid>requis
topicsobject[]

Initial per-topic subscription choices

Afficher les propriétés
Tableau de object
idstring<uuid>requis
subscriptionstringrequis
Valeurs autorisées :opt_inopt_out
Réponses
200

Batch processed

dataobject[]requis

One entry per successful item, in request order

Afficher les propriétés
Tableau de object
objectstringrequis
Valeurs autorisées :contact
indexintegerrequis

Position of the item in the request array

idstring<uuid>requis

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

statusstringrequis
Valeurs autorisées :createdupdatedskipped
countsobjectrequis

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

Afficher les propriétés
createdintegerrequis
updatedintegerrequis
skippedintegerrequis
failedintegerrequis
errorsobject[]

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

Afficher les propriétés
Tableau de object
indexintegerrequis
statusCodeintegerrequis
namestringrequis
messagestringrequis
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequis
namestringrequis
messagestringrequis
403

Plan limit reached (strict mode)

statusCodenumberrequis
namestringrequis
messagestringrequis
404

Unknown segment or topic (strict mode)

statusCodenumberrequis
namestringrequis
messagestringrequis
409

Contact already exists (strict mode, on_conflict=error)

statusCodenumberrequis
namestringrequis
messagestringrequis
422

Validation error

statusCodenumberrequis
namestringrequis
messagestringrequis
429

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

statusCodenumberrequis
namestringrequis
messagestringrequis
Essayer
Serveur
Autorisation
Paramètres
Corpsapplication/json
Requête
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"
      }
    ]
  }
]'
Réponse
{
  "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"
    }
  ]
}

Cette page vous a-t-elle été utile ?