Audience Contacts

The Audience Contacts endpoint can be used to retrieve all of the contacts that are part of an Audience filter. Since audience filters can generate a considerable amount of contacts, the call is meant to be executed in a start and next fashion.


The following request can be used to start the retrieval of audience contacts:

curl --location --request GET '<ID>/<FIELDS>' \
--header 'Authorization: Bearer <BOT_AUTH_TOKEN>' \

The ID field can be retrieved from the results of the Audiences List API.

The FIELDS parameters is, instead, a comma separated list of all of the fields that should be returned for each contact. Field names are identical to the variable names you can see from the Variables Panel of a conversation.

After the first request completes successfully, you can follow up each subsequent request using the following syntax:

curl --location --request GET '<ID>/readnext' \
--header 'Authorization: Bearer <BOT_AUTH_TOKEN>' \

Each request (start one included) will advance the read cursor by 256 contacts. Executing again the start request will reset the cursor position to the first contact.

Executing a next request after the last record will result in a Bad Request error response.


If the call is successful, a list of contacts will be returned. The content of the list may vary, depending on the FIELDS specified in the initial call.

Response Codes

This endpoint will reply with the following standard HTTP codes.




Ok. The request has been successfully fulfilled.


Bad Request. The call does not contain the data required to be fulfilled.


Not Found. The specified audience could not be found.


Unauthorized. The account associated to the token is not authorized

Last updated