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.
/contacts/batch/getAuthorizationBearer token · headerrequiredA BillionSend API key (bs_…).
application/jsoncontactsobject[]requiredUp to 1000 contacts, each by id or by email address (matched case-insensitively)
Show propertiesHide properties
objectidstring<uuid>emailstring<email>includestring[]Facets to attach to every contact returned: properties and/or topics
The contacts found, and the entries that matched none
objectstringrequiredlistdataobject[]requiredThe contacts found, in request order
Show propertiesHide properties
objectidstring<uuid>requiredemailstringrequiredfirst_namestring | nullrequiredlast_namestring | nullrequiredcreated_atstringrequiredunsubscribedbooleanrequiredOpt-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[]requiredBillionSend 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 propertiesHide properties
objectdomain_idstring<uuid> | nullrequiredNull when the domain has since been deleted from the team
namestringrequiredThe domain's name
unsubscribed_atstringrequiredverification_statusstring | nullrequiredBillionSend extension: the verdict of the contact's last deep verification (POST /verifications); null while it was never verified
validinvalidriskycatchallroledisposableunknownnullverified_atstring | nullrequiredWhen the last deep verification finished; null while never verified
propertiesobjectPresent with include=properties
topicsobject[]Present with include=topics
Show propertiesHide properties
objectidstring<uuid>requirednamestringrequireddescriptionstring | nullrequiredsubscriptionstringrequiredEffective choice: the contact's explicit one, else the topic's default
opt_inopt_outexplicitbooleanrequiredTrue when the contact or the API chose this; false when it is the topic's default
visibilitystringrequiredThe hosted preference page lists public topics only
publicprivateobjectstringrequiredcontactmissingobject[]requiredRequest entries that matched no contact of the team
Show propertiesHide properties
objectindexintegerrequiredPosition in the request's contacts array
idstring<uuid>emailstringMissing, malformed, unknown or revoked API key
statusCodenumberrequirednamestringrequiredmessagestringrequiredValidation error
statusCodenumberrequirednamestringrequiredmessagestringrequiredOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberrequirednamestringrequiredmessagestringrequired