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
ofapplication/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: |
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: |
user_identifier_type
optional
|
The type of identifier used for Type: enum Possible values: |
advertiser_account_id
sometimes required
|
The advertiser’s Twitter Ads account identifier. This is not the @handle for
the advertiser. Required for Type: string Example: |
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 Type: string Example: |
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: |
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 Type: string Example: |
membership_type
optional
|
The product that this request is intended for. Type: enum Possible values: |
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
}
]
}