How to generate an audience

Requesting an audience

When you’d like to identify customers that would be most interested in an offering, the Audience Targeting API is what you’re looking for. This offering could be anything from a news article that was just published to a promotion for a particular brand of shoes that is on sale right now. The Audience Targeting API is complementary to the Batch API. Whereas the Audience Targeting API is used to select an audience for a fixed promotion, the Batch API sends a personalized promotion to a fixed subset of users.

Audiences are requested synchronously and in real-time via the Audience Targeting API. For more information on the API Contract, see the API reference on the Audience Targeting API.

Examples

Here we highlight what the request would look like for some example use cases.

Push news article
Promote sale on high heels

In this example, we request an audience for a news article (promotion.id) about the Premier League competition: An important player in one of the top-3 clubs was hurt badly and will not be playing any more matches this season. We wish to send this to the 10,000 users (audience_size) who will find this news the most interesting. Our push notification server can handle batches of at most 1,000 users (limit). The push notification will be sent in the app (integration_type). To track the performance of our push notification, we give it a unique identifier (audience_id). The push notification’s title will be "What now!? Could Manchester City win the cup without the help of Kevin De Bruyne?" (audience_name).

{
  "audience": {
    "promotion": [
      {
        "id": "Art_Sports_Football_PremierLeague_019394050"
      }
    ],
    "limit": 1000,
    "audience_name": "What now!? Could Manchester City win the cup without the help of Kevin De Bruyne?",
    "integration_type": "push_notification_app",
    "audience_size": 10000,
    // "audience_configuration_id": "all_logged_in_users_app",
    "audience_id": "prem_lg_20200701T11:00:00"
  }
}

In this example, we request an audience for a promotion on last season’s high heels (promotion). We specify the IDs of all high heels on sale (promotion.id). We wish to send this to the 1,000 users (audience_size) who are most interested in these high heels. Our push notification server can handle any size batch, so we set limit to 1,000 users. The promotion will be sent via email (integration_type). To track the performance of our push notification, we allow Froomle to give it a unique identifier (audience_id), so we omit this field. The email’s title will be "FINAL WEEKEND - Discounts up to 50% on High Heels - Don’t miss out!" (audience_name).

{
  "audience": {
    "promotion": [
      {
        "id": "high_heel_1"
      },
      {
        "id": "high_heel_2"
      },
      ...
      {
          "id": "high_heel_10"
      }
    ],
    "limit": 1000,
    "audience_name": "FINAL WEEKEND - Discounts up to 50% on High Heels - Don't miss out!",
    "integration_type": "email",
    "audience_size": 1000
    // "audience_configuration_id": "promo_mailing_optin"
  }
}

Retrieving an audience in batches

Sometimes, you may want to request a very large audience for a promotion, but your push or email server prefers sending out promotions in smaller batches. The Audience Targeting API was designed to accommodate this use case. Two parameters control the size of the audience in the response: limit and audience_size. The initial response will contain only the limit first users of your total audience_size. Consecutive batches can be retrieved from the audiences API endpoint.

Requests to the audiences API endpoint don’t have a body. All parameters are URL-encoded.

Its parameters are:

audience_id: The Audience ID of the audience to retrieve, as returned in the response body of the original audience request.
offset: The rank of the first user that is to be returned.
limit: The number of subsequent users that are to be returned.

All parameters are required.

Examples:

offset = 1, limit = 3 returns users with ranks 1 (most relevant), 2, 3:

[
  {
    "id" : "948451",
    "user_type": "login"
  },
  {
    "id" : "643321",
    "user_type": "login"
  },
  {
    "id": "374890",
    "user_type": "login"
  }
]

offset = 7, limit = 5 returns recommendations with ranks 7, 8, 9, 10, and 11.

If offset + limit – 1 is greater than the number of recommendations generated for the list, then the remaining recommendations will be returned, which will be fewer than specified. If offset > audience_size, then no items will be returned.

Getting started

As soon as your Audience Targeting API has been activated by the Froomle engineering team at https://subdomain.froomle.com/api/environment/targeting/audiences/requests, you can start testing the API. Navigate to https://subdomain.froomle.com/api/ui and open up the audience section. The UI supplies an example audience request that should work out of the box, given that you have obtained the required authentication credentials. To request these authentication credentials, please contact the Froomle support team at support@froomle.com.