Documentation
Sign inGet started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

List contacts

GET
/v1/contacts
for 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_cursor
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.
Queryparameters
email
string
Return 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_number
array
Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers, and set limit to at least the number of values you pass: limit defaults to 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_id
string
Return 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.
q
string
Case-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.
identifier
string
Filter to contacts that have a specific identifier on file.
Possible values: email, phone_number
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.
include_total
boolean
When true, the response includes a total field with the total number of items matching the request's filters across all pages.
Response Payload
data
array of object
verplicht
Page of contact objects.
Onderliggende attributen tonen
data.id
string
verplicht
ID of the contact (con_-prefixed), accepted by every operation that takes a contact_id.
data.email
nullable string
verplicht
The 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_number
nullable string
verplicht
The contact's phone number in normalized international form (a leading + and four to 15 digits), which may differ from the form it was supplied in. Bird normalizes formatting but does not verify the number against numbering-plan metadata. Unique within the workspace. Carriers recycle disconnected numbers, so a long-stored number can come to belong to someone else; external_id is the durable key for your own records. Null when the contact has no phone number.
data.first_name
nullable string
The contact's first name. Available in broadcast templates as bird.contact.first_name.
data.last_name
nullable string
The contact's last name. Available in broadcast templates as bird.contact.last_name.
data.external_id
nullable string
Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
data.data
object
Custom 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.audiences
array of object
The audiences this contact belongs to, most-recently-joined first. Only present when listing contacts; omitted from every other contact operation.
Onderliggende attributen tonen
data.audiences.id
string
verplicht
ID of the referenced audience (adn_-prefixed).
data.audiences.name
string
verplicht
The audience's display name.
data.created_at
string
verplicht
data.updated_at
string
verplicht
next_cursor
nullable string
verplicht
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
verplicht
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
verplicht
Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.
total
nullable integer
Total number of items matching the request's filters across all pages. Present only when include_total=true was passed; otherwise null.