Audiences

Real-Time Audience API

POST tailored_audience_memberships

This Real-Time Audience API will enable partners to upload batched tailored audience information to Twitter for processing in real-time.

Batch Requests

  • The current maximum batch size is 100 for this endpoint.
  • All parameters are sent in the request body and a Content-Type of application/json is required.
  • Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses

The response returned by the Ads API contains two fields, a success_count and a total_count. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is not equal the success_count and total_count should be treated as an error condition, requiring a retry.

Batch Errors

  • Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
  • Item-level errors (eg. missing required parameters) are show in the response under the operation_errors object.

Note: This endpoint is currently in closed beta and not yet generally available.

Resource URL

https://ads-api.twitter.com/3/tailored_audience_memberships

Parameters

Name Description
operation_type
required

The per item operation type being performed. Currently, only the Update operation is supported, and can be used to create new tailored audience associations.

Type: enum

Possible values: Update
params
required

A JSON object containing all params for each user object (listed below).

Type: JSON
user_identifier
required

The unique ID that is used by the partner to identify the user.

Type: string

Example: LIUGKJHG-UGJHVHJ
user_identifier_type
optional

The type of identifier used for user_identifer.

Type: enum

Possible values: DEVICE_ID, EMAIL, HANDLE, PHONE_NUMBER, TALIST_PARTNER_USER_ID, TAWEB_PARTNER_USER_ID
advertiser_account_id
sometimes required

The advertiser’s Twitter Ads account identifier. This is not the @handle for the advertiser. Required for LIST_MEMBERSHIP and WEB_MEMBERSHIP, optional for WEB_OPTOUT.

Type: string

Example: 43853bhii879
audience_names
sometimes required

A comma separated list of tailored audiences to add this user to, identified by their audience names. If no existing audience is found for a provided audience name, a new audience will be created. Maximum length of this list: 100 Audiences. Required for LIST_MEMBERSHIP and WEB_MEMBERSHIP, optional for WEB_OPTOUT.

Type: string

Example: ads api users
effective_at
optional

The UTC time at which the tailored audience association(s) should take effect. Expressed in ISO 8601. Defaults to the current date and time.

Type: string

Example: 2017-07-05T07:00:00Z
expires_at
optional

The UTC time at which the tailored audience association(s) should expire. The specified time must be later than the value of effective_at. Expressed in ISO 8601. Defaults to your configured default expiration period (typically 30 days or 720 hours from effective_at).

Type: string

Example: 2017-07-05T07:00:00Z
membership_type
optional

The product that this request is intended for.

Type: enum

Possible values: LIST_MEMBERSHIP, WEB_MEMBERSHIP, WEB_OPTOUT

Example Request

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":"FTHHJHG-UITUVHJ",
         "user_identifier_type":"TAWEB_PARTNER_USER_ID",
         "audience_names":"Recent Sign-ups",
         "effective_at":"2015-08-01T00:00:00Z",
         "expires_at":"2015-09-01T00:00:00Z"
      }
   }
]

Example Response

{
  "data_type": "tailored_audience_membership",
  "data": [
    {
      "success_count": 1
    }
  ],
  "request": [
    {
      "total_count": 1
    }
  ]
}