Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau

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
Autorisierung
AuthorizationBearer-Token · headererforderlich

A BillionSend API key (bs_…).

Request-Body
erforderlichapplication/json
contactsobject[]erforderlich

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

min. 1 Elemente · max. 1000 Elemente
Eigenschaften anzeigen
Array von object
idstring<uuid>
emailstring<email>
includestring[]

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

Antworten
200

The contacts found, and the entries that matched none

objectstringerforderlich
Erlaubt:list
dataobject[]erforderlich

The contacts found, in request order

Eigenschaften anzeigen
Array von object
idstring<uuid>erforderlich
emailstringerforderlich
first_namestring | nullerforderlich
last_namestring | nullerforderlich
created_atstringerforderlich
unsubscribedbooleanerforderlich

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

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

Eigenschaften anzeigen
Array von object
domain_idstring<uuid> | nullerforderlich

Null when the domain has since been deleted from the team

namestringerforderlich

The domain's name

unsubscribed_atstringerforderlich
verification_statusstring | nullerforderlich

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

Erlaubt:validinvalidriskycatchallroledisposableunknownnull
verified_atstring | nullerforderlich

When the last deep verification finished; null while never verified

propertiesobject

Present with include=properties

topicsobject[]

Present with include=topics

Eigenschaften anzeigen
Array von object
idstring<uuid>erforderlich
namestringerforderlich
descriptionstring | nullerforderlich
subscriptionstringerforderlich

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

Erlaubt:opt_inopt_out
explicitbooleanerforderlich

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

visibilitystringerforderlich

The hosted preference page lists public topics only

Erlaubt:publicprivate
objectstringerforderlich
Erlaubt:contact
missingobject[]erforderlich

Request entries that matched no contact of the team

Eigenschaften anzeigen
Array von object
indexintegererforderlich

Position in the request's contacts array

idstring<uuid>
emailstring
401

Missing, malformed, unknown or revoked API key

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
422

Validation error

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
429

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

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
Ausprobieren
Server
Autorisierung
Bodyapplication/json
Anfrage
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"
  ]
}'
Antwort
{
  "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"
    }
  ]
}

War diese Seite hilfreich?