Overview

The Audience API was launched as part of v4 of the Ads API and with it, brings several improvements to the legacy Audiences endpoints. This new endpoint is backed by a new Audience processing backend, and brings several improvements in terms of stability, robustness and reliability. The purpose of this guide is to highlight the differences between the Audience API and the legacy Audience upload and management processes. 

Reference documentation can be found on the Audience API reference documentation page. 

Note: All Audience user data must be SHA-256 hashed prior to upload. More details, along with the accepted user identifier types and data normalization can be found on the user data page.

Changes to Audience Functionality

The following changes to Custom Audiences have been introduced as of v4 and any deprecated endpoints will no longer be available once v3 of the Ads API has been sunset:

• Deprecated TON Upload:
  • GET accounts/:account_id/custom_audience_changes
  • GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
  • POST accounts/:account_id/custom_audience_changes
  • PUT accounts/:account_id/custom_audiences/global_opt_out
• Deprecated Real Time Audiences:
  • POST custom_audience_memberships
• Custom Audience:
  • The list_type parameter will be removed from the request and response on all Custom Audience endpoints. This parameter was previously used to identify the user identifier type of the Audience (i.e., email, Twitter User ID, etc.) however Audiences now have the ability to accept multiple user identifiers for the same Audience thereby making this value irrelevant.
• General:
  • The Audience lookback window has been updated to match against users active within the past 90 days (from 30 days)
  • The minimum number of matched users required for an audience to be targetable has been decreased to 100 users (from 500 users)

Prerequisites

• Ads API access
• For access to the Audience endpoint, you will need to be added to an allowlist. Please fill this form and accept the new Twitter Ads Products and Services Agreement if initially accepted prior to 2018-08-01
  

Audience Upload Process

The following table lists the primary differences between the old and new Audience creation flows, with more details available further below:

Note Any audiences being updated or opted-out via the TON Upload path must have a corresponding list uploaded via the TON Upload endpoint and associated with an Audience using the custom_audience_changes endpoint.

Rate Limiting

The Audience API endpoint has a rate limit of 1500/1min per account. There are no limits on the number of users that can be sent in a single payload. The only constraints on the payload are:

1. Total number of operations: 2500 operations

2. Maximum payload size: 5,000,000 bytes

Audience User Management

In order to create a new Audience, the following steps are required

Create a new Custom Audience

Create a new Custom Audience "shell" using the POST custom_audience endpoint and retrieve the corresponding Custom Audience id. This step is required if creating an Audience from scratch. If updating an existing Audience, skip to the next section

Add Users to an Audience

Use the POST accounts/:account_id/custom_audiences/:custom_audience_id/users with the Custom Audience id and a sample payload like so:

POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

# All values must be hashed, unhashed values are used in this example for illustrative purposes
[
  {
    "operation_type": "Update",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "abc@twitter.com"
          ],
          "handle": [
            "twitter",
            "adsapi"
          ]
        },
        {
          "email": [
            "edf@twitter.com"
          ],
          "twitter_id": [
            "121291606",
            "17874544"
          ]
        }
      ]
    }
  }
]

In order to add a user to an Audience, use the operation_type Update. The new Audience interface enables the ability to pass in multiple user keys for a single user. Each object in the array of JSON objects corresponds to a single user. Using the example payload above, the request will add two users to an Audience, one with an email and handle and another with an email and twitter_id. 

Remove Users from an Audience

Similar to the process outlined for adding users, users can be removed from an audience using like so:

POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

# All values must be hashed, unhashed values are used in this example for illustrative purposes
[
  {
    "operation_type": "Delete",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "abc@twitter.com"
          ],
          "twitter_id": [
            "783214",
            "1225933934"
          ]
        },
        {
          "email": [
            "edf@twitter.com"
          ],
          "twitter_id": [
            "121291606",
            "17874544"
          ]
        }
      ]
    }
  }
]

The operation_type must be set to Delete and users will be matched on any keys that were present when adding users to the audience. For example, if a user was added to an audience using an email and twitter_id, then the same user can be removed using any one of these keys, i.e., either email or twitter_id or both.

Additionally, it is possible to add and remove users from an Audience within the same request. The endpoint supports multiple operation_type per request.

Opt-Out Users

With the deprecation of the global opt-out endpoint, partners are required to Delete any users that have opted-out of any Audiences. There are a few ways to achieve this:

1. Keep track of which users are part of which Audiences and remove these users individually from each Audience.
2. Remove the user from all Audiences associated with an Ads account.

General Best Practices

• We strongly recommend calling this endpoint in near real-time batches to avoid spiky queues which take longer to process and in general cause unnecessary load on our system. This also ensures users are available for campaign targeting sooner.
• A successful API call will return a success_count and total_count corresponding to the number of user objects that have been received in the request.
• This endpoint is atomic in nature, that is, either the entire request is successful or in case of any errors then the entire request will fail. In case of an error response, consumers of the API are recommended to fix the error and retry the request with the entire payload. 
• Upon failure, partners recommended to use an exponential backoff approach with retries. For example, retry immediately upon the first failure, retry after 1 minute after the second failure and retry after 5 minutes after the third consecutive failure, and so on