Skip to content
Esc
↑↓navigate↵open⌘Jpreview

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
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Request body
requiredapplication/json
contactsobject[]required

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

min items 1 · max items 1000
Show properties
Array of object
idstring<uuid>
emailstring<email>
includestring[]

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

Responses
200

The contacts found, and the entries that matched none

objectstringrequired
Allowed:list
dataobject[]required

The contacts found, in request order

Show properties
Array of object
idstring<uuid>required
emailstringrequired
first_namestring | nullrequired
last_namestring | nullrequired
created_atstringrequired
unsubscribedbooleanrequired

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

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

Show properties
Array of object
domain_idstring<uuid> | nullrequired

Null when the domain has since been deleted from the team

namestringrequired

The domain's name

unsubscribed_atstringrequired
verification_statusstring | nullrequired

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

Allowed:validinvalidriskycatchallroledisposableunknownnull
verified_atstring | nullrequired

When the last deep verification finished; null while never verified

propertiesobject

Present with include=properties

topicsobject[]

Present with include=topics

Show properties
Array of object
idstring<uuid>required
namestringrequired
descriptionstring | nullrequired
subscriptionstringrequired

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

Allowed:opt_inopt_out
explicitbooleanrequired

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

visibilitystringrequired

The hosted preference page lists public topics only

Allowed:publicprivate
objectstringrequired
Allowed:contact
missingobject[]required

Request entries that matched no contact of the team

Show properties
Array of object
indexintegerrequired

Position in the request's contacts array

idstring<uuid>
emailstring
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

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

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Bodyapplication/json
Request
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"
  ]
}'
Response
{
  "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"
    }
  ]
}

Was this page helpful?