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

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
Autorización
AuthorizationToken Bearer · headerobligatorio

A BillionSend API key (bs_…).

Cuerpo de la solicitud
obligatorioapplication/json
contactsobject[]obligatorio

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

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

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

Respuestas
200

The contacts found, and the entries that matched none

objectstringobligatorio
Valores permitidos:list
dataobject[]obligatorio

The contacts found, in request order

Mostrar propiedades
Array de object
idstring<uuid>obligatorio
emailstringobligatorio
first_namestring | nullobligatorio
last_namestring | nullobligatorio
created_atstringobligatorio
unsubscribedbooleanobligatorio

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[]obligatorio

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 propiedades
Array de object
domain_idstring<uuid> | nullobligatorio

Null when the domain has since been deleted from the team

namestringobligatorio

The domain's name

unsubscribed_atstringobligatorio
verification_statusstring | nullobligatorio

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

Valores permitidos:validinvalidriskycatchallroledisposableunknownnull
verified_atstring | nullobligatorio

When the last deep verification finished; null while never verified

propertiesobject

Present with include=properties

topicsobject[]

Present with include=topics

Mostrar propiedades
Array de object
idstring<uuid>obligatorio
namestringobligatorio
descriptionstring | nullobligatorio
subscriptionstringobligatorio

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

Valores permitidos:opt_inopt_out
explicitbooleanobligatorio

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

visibilitystringobligatorio

The hosted preference page lists public topics only

Valores permitidos:publicprivate
objectstringobligatorio
Valores permitidos:contact
missingobject[]obligatorio

Request entries that matched no contact of the team

Mostrar propiedades
Array de object
indexintegerobligatorio

Position in the request's contacts array

idstring<uuid>
emailstring
401

Missing, malformed, unknown or revoked API key

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
Cuerpoapplication/json
Solicitud
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"
  ]
}'
Respuesta
{
  "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"
    }
  ]
}

¿Te ha resultado útil esta página?