Audience Service API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Resolve an audience into participants

Suppose you want to notify all contacts with a specific label, such as VIP. Before you can send the notification, you need to resolve that audience into the individual contacts it represents.

To resolve an audience into participants:

1. Call List Audience Providers, filtering by participantTypes: ["CONTACT"] and scope: "SPECIFIC_SITE", to find a provider that can resolve contacts by label.

2. From the response, note the matching provider's id, in the format {appId}_{key}, and its inputSchema, which describes the parameters it needs.

3. Call List Participants, passing an audience built from that provider's id and the label ID as input data. For example:

   Copy

4. If the response's pagingMetadata.hasNext is true, call List Participants again, passing pagingMetadata.cursors.next as paging.cursor, to retrieve the next page of participants.

Estimate audience size before resolving participants

Suppose you're building an automation that notifies all contacts with the VIP label whenever some trigger occurs. You want to show the estimated size of that audience while the automation is being set up, without resolving the actual participants until the automation runs and the notification is actually sent.

To estimate audience size before resolving participants:

1. Call List Audience Providers and check the matching provider's implementedMethods.countParticipants field to see whether it supports counting.

2. Call Count Participants, passing the same audience you would use to resolve participants. For example:

   Copy

3. Read the count for the audience from the response, and store it with the automation or task definition to show the estimated size until it's run. If the provider doesn't support counting, count is 1 instead of an exact number.

4. When the automation's trigger fires, call List Participants with the same audience to resolve the actual participants to notify.