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",
"email": "alice@acme.com",
"phone_number": "+31612345678",
"audiences": [
{
"id": "adn_01krdgeqcxet5s7t44vh8rt9mg",
"name": "Newsletter subscribers"
}
],
"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.
Paramètres de requête
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.
Contenu de la réponse
next_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.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.