Real-Time Audience Overview
Twitter works with Partners to make customized audience segments available to advertisers for targeting in Twitter Ads campaigns. The Real Time Audience API allows partners and advertisers to create and update audiences based on a variety of ID types to be activated for ad targeting. The list of supported ID types can be found on the Audiences File Data page. This allows newly created audiences to be activated in near real time, however true audience size estimates may take up to a few days. All incremental updates to existing Audiences are also processed in real time.
Note: Partners that are sending data with a p_id must ensure that the they complete the ID sync process with Twitter, in order to identify audience segments, and update audience membership status via calls to the provided API endpoint. Please take a look at our ID Sync page for details.
Reference documentation can be found on the POST tailored_audience_memberships page.
Prerequisites
- Ads API access
- Approval for access to Real-Time Audience API
Sections
Sending Membership Updates¶
Twitter must be notified of audience membership updates via the POST tailored_audience_memberships endpoint.
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.
Here is guidance for completing specific scenarios with audience updates:
Adding Users to Audience:
The method of adding users to an audience is to include them in a batch call to Tailored Audience Memberships endpoint, at which time a new audience will be created if the audience_name does not already exist for the given advertiser_account_id.
POST https://ads-api.twitter.com/3/tailored_audience_memberships
[
{
"operation_type":"Update",
"params":{
"membership_type": "WEB_MEMBERSHIP",
"advertiser_account_id":18h7jk9hy,
"user_identifier":"IUGKJHG-UGJHVHJ",
"user_identifier_type":"TAWEB_PARTNER_USER_ID",
"audience_names":"Recent Site Visitors, Recent Sign-ups",
"effective_at":"2015-07-20T23:29:09Z",
"expires_at":"2015-11-22T23:29:09Z"
}
},
{
"operation_type":"Update",
"params":{
"membership_type": "LIST_MEMBERSHIP",
"advertiser_account_id":18h76sdkj,
"user_identifier":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"user_identifier_type":"TWITTER_ID",
"audience_names":"Recent Sign-ups",
"effective_at":"2015-08-01T00:00:00Z",
"expires_at":"2015-09-01T00:00:00Z"
}
},
{
"operation_type":"Update",
"params":{
"membership_type": "LIST_MEMBERSHIP",
"advertiser_account_id":18h76sdkj,
"user_identifier":"FTHHJHG-UITUVHJ",
"user_identifier_type":"TALIST_PARTNER_USER_ID",
"audience_names":"Past Sign-ups",
"effective_at":"2015-08-01T00:00:00Z",
"expires_at":"2015-09-01T00:00:00Z"
}
}
]
Appending / Modifying Segment Membership for a Set of Users:
To add or modify audience membership for users, simply call the endpoint with the audience names to append/modify for the given user_identifier. New memberships for that user will work in an additive way, and existing membership will be updated as per the attributes given. That is, membership updates to an existing audience_name will be additive if the user_identifier does not already belong to the audience. If the user_identifier does exist, membership updates will modify the attributes of the existing member.
POST https://ads-api.twitter.com/3/tailored_audience_memberships
[
{
"operation_type":"Update",
"params":{
"membership_type": "WEB_MEMBERSHIP",
"advertiser_account_id":18h7jk9hy,
"user_identifier":"IUGKJHG-UGJHVHJ",
"user_identifier_type":"TAWEB_PARTNER_USER_ID",
"audience_names":"Recent Site Visitors",
"effective_at":"2015-07-20T23:29:09Z",
"expires_at":"2015-11-22T23:29:09Z"
}
},
{
"operation_type":"Update",
"params":{
"membership_type": "LIST_MEMBERSHIP",
"advertiser_account_id":18h76sdkj,
"user_identifier":"FTHHJHG-UITUVHJ",
"user_identifier_type":"TALIST_PARTNER_USER_ID",
"audience_names":"Recent Purchasers",
"effective_at":"2015-08-01T00:00:00Z",
"expires_at":"2015-09-01T00:00:00Z"
}
}
]
Removing Users from an Audience:
By default (without setting expires_at parameter) users will be expired after a default period of time based upon your partner configuration, typically 30 days. If you want to expire a user sooner, set the expires_at parameter to an earlier date. To immediately remove a user, call the endpoint to set expires_at to a date in the past. This can be done for a subset of audience memberships (you do not need to send every membership with every call).
POST https://ads-api.twitter.com/3/tailored_audience_memberships
[{
"operation_type":"Update",
"params":{
"membership_type": "WEB_MEMBERSHIP",
"advertiser_account_id":18h7jk9hy,
"user_identifier":"IUGKJHG-UGJHVHJ",
"user_identifier_type":"TAWEB_PARTNER_USER_ID",
"audience_names":"Recent Site Visitors, Recent Sign-ups",
"effective_at":"2015-07-20T23:29:09Z",
"expires_at":"2015-07-20T23:29:09Z"
}
}]
Checking an Audience Size and Targeting Availability:
Generally, audiences will transition to a targetable state in real-time, however the true estimates for audience size may take significantly longer to finalize (24-60 hours).
To confirm if audience updates have been processed, simply call GET accounts/:account_id/tailored_audiences and confirm that the audiences created are matched to audience names from your membership batch calls. You can periodically ping this endpoint (no more frequently than every 15 minutes) to confirm when the audience transitions to a targetable state.
Opt-Out File Configuration and Sending Opt-Out Files¶
Partners should provide Twitter with a list of users that to the partner’s best knowledge have selected to opt-out of targeted ad delivery. These updates can be submitted via the POST tailored_audience_memberships.
POST https://ads-api.twitter.com/3/tailored_audience_memberships
[{
"operation_type": "Update",
"params": {
"membership_type": "WEB_OPTOUT",
"user_identifier": "2938d90b092be8311c15ddd3020db078afce230bef68c053d18e5728259",
"user_identifier_type": "TWITTER_ID",
"effective_at": "2016-08-02T07:08:17Z",
"expires_at": "2016-09-01T07:08:17Z88"
}
}]
Best Practices¶
- Rate Limits: The rate-limits for this endpoints are measured in Queries Per Second (QPS). The limit for this endpoint is 100 QPS. All HTTP Status Codes and corresponding enum values are documented on the API Error Codes & Responses page .
- The batch endpoint can support a maximum of 100 entities per request
- This endpoint should be used to send incremental updates to memberships instead of the entire list therefore the partner should maintain a list of all membership request submitted, and only submit additions/removals/updates to these lists.
- Real-Time Audiences are activated for targeting, as well as updated in near real-time, however please note that the true estimate for the audience size may still take up to a few days.
- Please refer to our FAQ page for additional information
- The effective_at timestamp should always be lesser than the expires_at for all additions (if not using the default values)
- For all deletions, simply set the expires_at == effective_at = current timestamp