跳到内容
Esc
↑↓导航↵打开⌘J预览

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
授权
AuthorizationBearer 令牌 · header必填

A BillionSend API key (bs_…).

查询参数
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).

默认值:"error"
允许值:errorskipupsert
标头参数
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.

允许值:strictpermissive
请求体
必填application/json
CreateContactRequest 数组
emailstring<email>必填

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

显示属性
object 数组
idstring<uuid>必填
topicsobject[]

Initial per-topic subscription choices

显示属性
object 数组
idstring<uuid>必填
subscriptionstring必填
允许值:opt_inopt_out
响应
200

Batch processed

dataobject[]必填

One entry per successful item, in request order

显示属性
object 数组
objectstring必填
允许值:contact
indexinteger必填

Position of the item in the request array

idstring<uuid>必填

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

statusstring必填
允许值:createdupdatedskipped
countsobject必填

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

显示属性
createdinteger必填
updatedinteger必填
skippedinteger必填
failedinteger必填
errorsobject[]

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

显示属性
object 数组
indexinteger必填
statusCodeinteger必填
namestring必填
messagestring必填
401

Missing, malformed, unknown or revoked API key

statusCodenumber必填
namestring必填
messagestring必填
403

Plan limit reached (strict mode)

statusCodenumber必填
namestring必填
messagestring必填
404

Unknown segment or topic (strict mode)

statusCodenumber必填
namestring必填
messagestring必填
409

Contact already exists (strict mode, on_conflict=error)

statusCodenumber必填
namestring必填
messagestring必填
422

Validation error

statusCodenumber必填
namestring必填
messagestring必填
429

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

statusCodenumber必填
namestring必填
messagestring必填
试一试
服务器
授权
参数
请求体application/json
请求
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"
      }
    ]
  }
]'
响应
{
  "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"
    }
  ]
}

这个页面有帮助吗?