List contacts in a list
This endpoint will return a list of contacts in the specified list.
Authorizations
Path parameters
workspaceIdstring · uuidRequiredExample:
Your workspace identifier.
b4e02c85-c6d2-4b15-8885-e09671799c61
listIdstring · uuidRequiredExample:
The ID of a list.
b4e02c85-c6d2-4b15-8885-e09671799c61
Query parameters
limitinteger · min: 1 · max: 100OptionalDefault:
Limits the number of results to return. The default value is 10, the minimum is one and the maximum is 100.
10
pageTokenstring · max: 8000OptionalExample:
Pagination token that keeps of track of the current position in the list.
nextPageToken123
reversebooleanOptionalDefault:
Order in which to retrieve the results.
false
Responses
200
A list of contacts was returned. The list can be empty if no contacts are found.
application/json
Responseall of
404
The workspace or list was not found.
application/json
get
GET /workspaces/{workspaceId}/lists/{listId}/contacts HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Accept: */*
{
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"computedDisplayName": "John Doe",
"createdAt": "2025-07-14T04:21:29.393Z",
"updatedAt": "2025-07-14T04:21:29.393Z",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000",
"featuredIdentifiers": [
{
"key": "emailaddress",
"value": "[email protected]"
}
],
"attributes": {
"firstName": "John",
"lastName": "Smith",
"rating": 9.6,
"cookiesAccepted": false,
"labels": [
"A",
"B",
"C"
]
},
"identifierCount": 2,
"accountIds": [
"123e4567-e89b-12d3-a456-426614174000"
],
"listIds": [
"123e4567-e89b-12d3-a456-426614174000"
]
}
],
"nextPageToken": "text"
}
Examples
Let's establish some of our data that will be used in the following examples:
Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352
AccessKey: abcd
List ID: 123e4567-e89b-12d3-a456-426614174000
List contacts from a list
In this example, we are listing all the contacts from a list given given the list ID.
curl -X GET "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/lists/123e4567-e89b-12d3-a456-426614174000/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd"
Last updated
Was this helpful?