List contacts
GET
/v1/contacts
curl -X GET "https://us1.platform.bird.com/v1/contacts" \
-H "Authorization: Bearer $TOKEN" \
--url-query "email=user@example.com" \
--url-query "external_id=user_12345" \
--url-query "q=acme.com" \
--url-query "limit=25"Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact email or external_id, or search by email substring with q.
Abfrageparameter
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.
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.
q
string
Case-insensitive substring match against the contact's email address.
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.
Antwort-Payload
data
array of object
erforderlich
Page of contact objects.
Untergeordnete Attribute anzeigen
data.id
string
erforderlich
ID of the contact (con_-prefixed), accepted by every operation that takes a contact_id.
data.email
string
erforderlich
The contact's email address, stored trimmed and lowercased. Unique within the workspace.
data.first_name
nullable string
The contact's first name. Available in broadcast templates as the contact.first_name variable.
data.last_name
nullable string
The contact's last name. Available in broadcast templates as the contact.last_name variable.
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 as template variables in broadcasts. Each key is a property created via the contact properties API, and each value is a string, number, or boolean 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.channels
array of string
Channels this contact can be reached on, derived from the identifiers it has. A contact with an email address includes email. More values are added as a contact gains identifiers for other channels.
data.created_at
string
erforderlich
data.updated_at
string
erforderlich
next_cursor
nullable string
erforderlich
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
erforderlich
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
erforderlich
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.