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

Read contacts in bulk

BillionSend extension: returns up to 1000 contacts by id or by email address in one request, in request order, optionally with their properties and topic subscriptions. Entries that match no contact are listed under missing instead of failing the call. One call counts as one request against the rate limit.

POST/contacts/batch/get
Autorização
AuthorizationToken Bearer · headerobrigatório

A BillionSend API key (bs_…).

Corpo da requisição
obrigatórioapplication/json
contactsobject[]obrigatório

Up to 1000 contacts, each by id or by email address (matched case-insensitively)

mín. 1 itens · máx. 1000 itens
Mostrar propriedades
Array de object
idstring<uuid>
emailstring<email>
includestring[]

Facets to attach to every contact returned: properties and/or topics

Respostas
200

The contacts found, and the entries that matched none

objectstringobrigatório
Valores permitidos:list
dataobject[]obrigatório

The contacts found, in request order

Mostrar propriedades
Array de object
idstring<uuid>obrigatório
emailstringobrigatório
first_namestring | nullobrigatório
last_namestring | nullobrigatório
created_atstringobrigatório
unsubscribedbooleanobrigatório

Opt-out from every marketing send of the team, whichever domain sends. A recipient's own unsubscribe never sets it: that is recorded for the domain whose email carried the link (see unsubscribed_domains).

unsubscribed_domainsobject[]obrigatório

BillionSend extension: the domains this contact unsubscribed from through a link in their email. Marketing sends from those domains skip the contact; other domains still reach them. The team-wide opt-out is unsubscribed, not an entry here. Remove an entry with DELETE /unsubscribes/{id}.

Mostrar propriedades
Array de object
domain_idstring<uuid> | nullobrigatório

Null when the domain has since been deleted from the team

namestringobrigatório

The domain's name

unsubscribed_atstringobrigatório
verification_statusstring | nullobrigatório

BillionSend extension: the verdict of the contact's last deep verification (POST /verifications); null while it was never verified

Valores permitidos:validinvalidriskycatchallroledisposableunknownnull
verified_atstring | nullobrigatório

When the last deep verification finished; null while never verified

propertiesobject

Present with include=properties

topicsobject[]

Present with include=topics

Mostrar propriedades
Array de object
idstring<uuid>obrigatório
namestringobrigatório
descriptionstring | nullobrigatório
subscriptionstringobrigatório

Effective choice: the contact's explicit one, else the topic's default

Valores permitidos:opt_inopt_out
explicitbooleanobrigatório

True when the contact or the API chose this; false when it is the topic's default

visibilitystringobrigatório

The hosted preference page lists public topics only

Valores permitidos:publicprivate
objectstringobrigatório
Valores permitidos:contact
missingobject[]obrigatório

Request entries that matched no contact of the team

Mostrar propriedades
Array de object
indexintegerobrigatório

Position in the request's contacts array

idstring<uuid>
emailstring
401

Missing, malformed, unknown or revoked API key

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
Corpoapplication/json
Requisição
curl -X POST 'https://api.billionsend.com/contacts/batch/get' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "contacts": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "user@example.com"
    }
  ],
  "include": [
    "properties"
  ]
}'
Resposta
{
  "object": "list",
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "created_at": "string",
      "unsubscribed": true,
      "unsubscribed_domains": [
        {
          "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
          "name": "string",
          "unsubscribed_at": "string"
        }
      ],
      "verification_status": "valid",
      "verified_at": "string",
      "properties": {
        "property1": {
          "type": "string",
          "value": "string"
        },
        "property2": {
          "type": "string",
          "value": "string"
        }
      },
      "topics": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "description": "string",
          "subscription": "opt_in",
          "explicit": true,
          "visibility": "public"
        }
      ],
      "object": "contact"
    }
  ],
  "missing": [
    {
      "index": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "string"
    }
  ]
}

Esta página foi útil?