Checking audience membership

Learn how to check if a user belongs to an audience using WLL APIs, with both async and sync approaches.

Overview

In this tutorial, you’ll check whether a user belongs to an audience in the White Label Loyalty (WLL) platform. You’ll learn two ways of doing this with the API:

1. Eventually consistent (async) checks.

2. Strongly consistent (sync) checks.

By the end, you’ll be able to:

• Create an audience in the console for users with at least one reported event.

• Verify audience membership using both async and sync APIs.

• Understand when each approach is appropriate.

---

Prerequisites

Before starting, make sure you have:

• Access to the Loyalty Console with your tenant and tenant API key

• Completed the tutorial Reporting your first event

• A user ID from the previous tutorial

• An admin API token (for impersonation) or the user’s own token

• A tool to make API requests (curl, Postman, or your preferred language)

---

Instructions

1

Create an audience

Follow this tutorial in our product docs: Create an audience of users who have or haven't reported one or more events.

Use the VISITED_VENUE event type you created in the tutorial Reporting your first event.

When the audience is created, an initial calculation runs across the entire user base. At some point, the user from Tutorial 2 should appear in the audience. You can wait for this user to appear under the audience members in the console or move on to step 2.

Keep the audience ID created here handy for the next steps.

2

Eventually consistent (async) check

Use this approach when slight delays in audience calculation are acceptable (e.g., segmentation for marketing campaigns).

Audience membership is calculated asynchronously in the background (via daily cron, triggered by new events, or manual recalculation).

To check membership after the async calculation, call the GET /audiences/:id/results endpoint.

Request

Admin token + impersonation

curl -X GET "https://api.staging.rewards.wlloyalty.net/v1/audiences/<audience_id>/results" \
  -H "Authorization: Bearer <admin_token>" \
  -H "x-api-key: <your_tenant_api_key>" \
  -H "x-impersonate: <user_id>"

User's own token

Responses

❌ User not in audience. For the above user, this could indicate that the background async calculation hasn't completed yet:

{
  "status": "success",
  "data": []
}

✅ User in audience. This indicates the calculation is done and the user we checked this audience for does in fact belong to this audience:

{
  "status": "success",
  "data": [
    {
      "accountNumber": 1000123,
      "isRestricted": false,
      "authIdentifier": "<user_auth_id>",
      "id": "<user_id>",
      "createdAt": "2023-11-29T06:40:25.259Z",
      "updatedAt": "2023-11-29T06:40:25.259Z",
      "externalIdentifier": null,
      "flags": {
        "genderProvided": true
      }
    }
  ]
}

3

Strongly consistent (sync) check

Use this approach when immediate correctness matters, e.g., showing or hiding features in an app (lock screen, gating functionality).

For real-time membership checks, call POST /audiences/syncly-search-results. This calculates audience membership on demand, which can be slower than async results.

Request

curl

curl -X POST "https://api.staging.rewards.wlloyalty.net/v1/audiences/syncly-search-results" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your_tenant_api_key>" \
  -d '{
    "audienceIds": ["<audience_id>"]
  }'

Node.js

Response

This returns a key value pair of audience IDs to a boolean suggesting whether the user is in the audience. For the user in question, we expect this to be the response.

{
  "status": "success",
  "data": {
    "<audience_id>": true
  }
}

Recap

• You created an audience in the console based on reported events.

• You checked membership using the async API (eventually consistent).

• You checked membership using the sync API (strongly consistent).

• You learned when to use each approach.

---

Assessment

Try the following:

1. Fire the VISITED_VENUE event for another user. Wait for the reactive audience recalculation, then check membership for this new user using the async API.

2. Fire the VISITED_VENUE event for a third user, but immediately call the syncly search results API to confirm membership without waiting for the background calculation.

3. Add another audience and check membership for multiple audiences in one sync request.

4. Compare the results between async and sync checks for the same user.

---

Next steps

• See Audiences for deeper explanation

• See the Audience API reference

• See the Audience syncly search results API reference