List contacts
/v1/contactsfor await (const contact of bird.contacts.list({ q: "acme.com" })) {
console.log(contact.id, contact.email);
}
const page = await bird.contacts.list({ limit: 50 }); // page.data, page.next_cursorfor contact in client.contacts.list(q="acme.com"):
print(contact.id, contact.email)for contact, err := range client.Contacts.List(context.Background(), bird.ContactListParams{Limit: 50}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(contact.Id, contact.Email)
}foreach ($bird->contacts->list(['q' => 'acme.com']) as $contact) {
echo $contact->getId(), ' ', $contact->getEmail(), "\n";
}bird contacts listcurl -X GET "https://us1.platform.bird.com/v1/contacts" \
-H "Authorization: Bearer $TOKEN" \
--url-query "email=user@example.com" \
--url-query "phone_number=+31612345678,+31698765432" \
--url-query "external_id=user_12345" \
--url-query "q=acme.com" \
--url-query "identifier=email" \
--url-query "limit=25" \
--url-query "include_total=false"{
"data": [
{
"id": "con_01krdgeqcxet5s7t44vh8rt9mg",
"audiences": [
{
"id": "adn_01krdgeqcxet5s7t44vh8rt9mg"
}
],
"created_at": "2026-05-20T09:14:52Z",
"updated_at": "2026-05-25T16:42:01Z"
}
],
"next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
"prev_cursor": null,
"refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact email, phone_number, or external_id, or search by email, first name, last name, or phone substring with q. Repeat phone_number to resolve up to 50 numbers to their contacts in one request, raising limit to at least the number of values you pass. Pass include_total=true to add the total number of matching contacts to the response.
Query Parameters
emailstringReturn the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page.
phone_numberarrayReturn the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set limit to at least the number of values you pass. The default limit is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so phone_number=a&phone_number=b&email=c asks for a contact whose phone number is a or b and whose email is c. Encode the leading plus sign as %2B (an unencoded + arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page.
external_idstringReturn the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page.
qstringCase-insensitive substring match against the contact's email address, first name, last name, or phone number. Phone matching is over the digits of the international form, so a full pasted number, a formatted number, or trailing digits all match; a national form with a leading trunk zero does not.
identifierstringFilter to contacts that have a specific identifier on file.
Possible values: email, phone_number
limitintegerMaximum number of items to return per page.
starting_afterstringCursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_beforestringCursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.
include_totalbooleanWhen true, the response includes a total field with the total number of items matching the request's filters across all pages.
Response Payload
dataPage of contact objects.
Show child attributes
data.idID of the contact, accepted by every operation that takes a contact_id.
data.emailThe contact's email address, in its stored form, trimmed and lowercased before uniqueness is checked. Unique within the workspace. null when the contact has no email address.
data.phone_numberThe contact's phone number in normalized international form: a leading + and four to 15 digits. We normalize formatting but do not verify the number against numbering-plan metadata. The number is unique within the workspace. Because carriers recycle disconnected numbers, use external_id as the durable key for your own records. null when the contact has no phone number.
data.first_nameThe contact's first name. Available in broadcast templates as bird.contact.first_name.
data.last_nameThe contact's last name. Available in broadcast templates as bird.contact.last_name.
data.external_idYour own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
data.dataCustom property values for this contact, available in broadcast templates as bird.contact.<key>. Each key is a property created via the contact properties API, and each value is a string, number, boolean, or RFC 3339 datetime matching the property's declared type (strings up to 500 characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here.
data.audiencesThe audiences this contact belongs to, most-recently-joined first. Only present when listing contacts; omitted from every other contact operation.
Show child attributes
data.audiences.idID of the referenced audience.
data.audiences.nameThe audience's display name.
data.created_atdata.updated_atnext_cursorCursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.
prev_cursorCursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.
refresh_cursorRefresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.
totalTotal number of items matching the request's filters across all pages. Present only when include_total=true was passed; otherwise null.
Related resources
Continue with the documentation, guides and examples for this topic.