List contacts in a list

List contacts in a list.

get

https://api.bird.comhttp://localhost:3000https://api.bird.ai

/workspaces/{workspaceId}/lists/{listId}/contacts

This endpoint will return a list of contacts in the specified list.

Authorizations

MessageBird_userMessageBird_accessKey

AuthorizationstringRequired

An access token issued to a user.

Path parameters

workspaceIdstring · uuidRequired

Your workspace identifier.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

listIdstring · uuidRequired

The ID of a list.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return. The default value is 10, the minimum is one and the maximum is 100.

Default: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list.

Example: nextPageToken123

reversebooleanOptional

Order in which to retrieve the results.

Default: false

Responses

200

A list of contacts was returned. The list can be empty if no contacts are found.

application/json

nextPageTokenstringOptional

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

404

The workspace or list was not found.

application/json

get

/workspaces/{workspaceId}/lists/{listId}/contacts

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/lists/{listId}/contacts HTTP/1.1
Host: api.bird.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "computedDisplayName": "John Doe",
      "createdAt": "2026-04-01T09:59:01.670Z",
      "updatedAt": "2026-04-01T09:59:01.670Z",
      "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"
      ],
      "companyRefs": [
        "text"
      ],
      "isAnonymous": true
    }
  ],
  "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.

Request

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"

Response (200 OK)