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

The unique identifier of the workspace.

listIdstring · uuidRequired

The ID of a list.

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

Query parameters

limitinteger · max: 100Optional

Limits the number of results to return.

Default: 25

pageTokenstringOptional

The cursor that keeps track of the current position in the results.

reversebooleanOptional

Reverses the order in which the results are returned.

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 requested resource 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": [
    {
      "accountIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "attributes": {
        "cookiesAccepted": false,
        "firstName": "John",
        "labels": [
          "A",
          "B",
          "C"
        ],
        "lastName": "Smith",
        "rating": 9.6
      },
      "companyRefs": [
        "text"
      ],
      "computedDisplayName": "John Doe",
      "createdAt": "2026-07-20T00:49:13.626Z",
      "featuredIdentifiers": [
        {
          "key": "emailaddress",
          "value": "[e-mail]"
        }
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierCount": 2,
      "isAnonymous": true,
      "listIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "updatedAt": "2026-07-20T00:49:13.626Z",
      "workspaceId": "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.

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)