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 "search=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 search.
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.
search
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
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.
data.last_name
nullable string
The contact's 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 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.
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.