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/getAuthorizationToken Bearer · headerobrigatórioA BillionSend API key (bs_…).
application/jsoncontactsobject[]obrigatórioUp to 1000 contacts, each by id or by email address (matched case-insensitively)
Mostrar propriedadesOcultar propriedades
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
objectstringobrigatóriolistdataobject[]obrigatórioThe contacts found, in request order
Mostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatórioemailstringobrigatóriofirst_namestring | nullobrigatóriolast_namestring | nullobrigatóriocreated_atstringobrigatóriounsubscribedbooleanobrigatórioOpt-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[]obrigatórioBillionSend 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 propriedadesOcultar propriedades
objectdomain_idstring<uuid> | nullobrigatórioNull when the domain has since been deleted from the team
namestringobrigatórioThe domain's name
unsubscribed_atstringobrigatórioverification_statusstring | nullobrigatórioBillionSend extension: the verdict of the contact's last deep verification (POST /verifications); null while it was never verified
validinvalidriskycatchallroledisposableunknownnullverified_atstring | nullobrigatórioWhen the last deep verification finished; null while never verified
propertiesobjectPresent with include=properties
topicsobject[]Present with include=topics
Mostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatórionamestringobrigatóriodescriptionstring | nullobrigatóriosubscriptionstringobrigatórioEffective choice: the contact's explicit one, else the topic's default
opt_inopt_outexplicitbooleanobrigatórioTrue when the contact or the API chose this; false when it is the topic's default
visibilitystringobrigatórioThe hosted preference page lists public topics only
publicprivateobjectstringobrigatóriocontactmissingobject[]obrigatórioRequest entries that matched no contact of the team
Mostrar propriedadesOcultar propriedades
objectindexintegerobrigatórioPosition in the request's contacts array
idstring<uuid>emailstringMissing, malformed, unknown or revoked API key
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioValidation error
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatório