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

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

A BillionSend API key (bs_…).

Corps de la requête
requisapplication/json
contactsobject[]requis

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

min 1 éléments · max 1000 éléments
Afficher les propriétés
Tableau de object
idstring<uuid>
emailstring<email>
includestring[]

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

Réponses
200

The contacts found, and the entries that matched none

objectstringrequis
Valeurs autorisées :list
dataobject[]requis

The contacts found, in request order

Afficher les propriétés
Tableau de object
idstring<uuid>requis
emailstringrequis
first_namestring | nullrequis
last_namestring | nullrequis
created_atstringrequis
unsubscribedbooleanrequis

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

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

Afficher les propriétés
Tableau de object
domain_idstring<uuid> | nullrequis

Null when the domain has since been deleted from the team

namestringrequis

The domain's name

unsubscribed_atstringrequis
verification_statusstring | nullrequis

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

Valeurs autorisées :validinvalidriskycatchallroledisposableunknownnull
verified_atstring | nullrequis

When the last deep verification finished; null while never verified

propertiesobject

Present with include=properties

topicsobject[]

Present with include=topics

Afficher les propriétés
Tableau de object
idstring<uuid>requis
namestringrequis
descriptionstring | nullrequis
subscriptionstringrequis

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

Valeurs autorisées :opt_inopt_out
explicitbooleanrequis

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

visibilitystringrequis

The hosted preference page lists public topics only

Valeurs autorisées :publicprivate
objectstringrequis
Valeurs autorisées :contact
missingobject[]requis

Request entries that matched no contact of the team

Afficher les propriétés
Tableau de object
indexintegerrequis

Position in the request's contacts array

idstring<uuid>
emailstring
401

Missing, malformed, unknown or revoked API key

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
Corpsapplication/json
Requête
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"
  ]
}'
Réponse
{
  "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"
    }
  ]
}

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