Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

List an audience's contacts

GET
/v1/audiences/{audience_id}/contacts
for await (const member of bird.audiences.listContacts("adn_01krdgeqcxet5s7t44vh8rt9mg")) {
  console.log(member.contact.id, member.joined_at);
}
Reactie200
{
  "data": [
    {
      "contact": {
        "id": "con_01krdgeqcxet5s7t44vh8rt9mg",
        "audiences": [
          {
            "id": "adn_01krdgeqcxet5s7t44vh8rt9mg"
          }
        ],
        "created_at": "2026-05-20T09:14:52Z",
        "updated_at": "2026-05-25T16:42:01Z"
      },
      "audiences": [
        {
          "id": "adn_01krdgeqcxet5s7t44vh8rt9mg"
        }
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Lists the contacts in a static audience as a cursor page, ordered by the time each contact joined the audience, most recent first. Each entry is the contact together with the time it joined.

Parameters

audience_idstring

ID of the audience whose contacts to list.

Queryparameters

qstring

Case-insensitive substring match against a contact's email address or the digits in its international phone number.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Response Payload

data
array of object
verplicht

Page of audience members, each a contact paired with the time it joined the audience.

Onderliggende attributen tonen
data.contact
object
verplicht
Onderliggende attributen tonen
data.contact.id
string
verplicht

ID of the contact, accepted by every operation that takes a contact_id.

data.contact.email
nullable string
verplicht

The contact's email address, in its stored form, trimmed and lowercased before uniqueness is checked. Unique within the workspace. null when the contact has no email address.

data.contact.phone_number
nullable string
verplicht

The contact's phone number in normalized international form: a leading + and four to 15 digits. We normalize formatting but do not verify the number against numbering-plan metadata. The number is unique within the workspace. Because carriers recycle disconnected numbers, use external_id as the durable key for your own records. null when the contact has no phone number.

data.contact.first_name
nullable string

The contact's first name. Available in broadcast templates as bird.contact.first_name.

data.contact.last_name
nullable string

The contact's last name. Available in broadcast templates as bird.contact.last_name.

data.contact.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.contact.data
object

Custom property values for this contact, available in broadcast templates as bird.contact.<key>. Each key is a property created via the contact properties API, and each value is a string, number, boolean, or RFC 3339 datetime 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.contact.audiences
array of object

The audiences this contact belongs to, most-recently-joined first. Only present when listing contacts; omitted from every other contact operation.

Onderliggende attributen tonen
data.contact.audiences.id
string
verplicht

ID of the referenced audience.

data.contact.audiences.name
string
verplicht

The audience's display name.

data.contact.created_at
string
verplicht
data.contact.updated_at
string
verplicht
data.joined_at
string
verplicht

When this contact joined the audience. Members are listed in join order, most recent first.

data.audiences
array of object

The audiences this contact belongs to, including the one being listed, most-recently-joined first.

Onderliggende attributen tonen
data.audiences.id
string
verplicht

ID of the referenced audience.

data.audiences.name
string
verplicht

The audience's display name.

next_cursor
nullable string
verplicht

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor
nullable string
verplicht

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor
nullable string
verplicht

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Gerelateerde bronnen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht