Audiences
Audience API
POST accounts/:account_id/tailored_audiences/:tailored_audience_id/users¶
This endpoint will allow partners to add, update and remove users from a given tailored_audience_id
. The endpoint will also accept multiple user identifier types per user as well.
All data being provided in the users
field of the request must be hashed using SHA256
and normalized.
Batch Requests
- The current maximum batch size is 2500 for this endpoint. The batch size is determined by the number of entries in the
users
field, regardless of theoperation_type
- The rate limits for this endpoint are 800 per 1 minute window
- 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. - The index of the error in the
operation_errors
refers to the index in the input item, with the corresponding error message
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/tailored_audiences/:tailored_audience_id/users
Parameters¶
Name | Description |
---|---|
operation_type required |
The per Type: enum Possible values: |
params required |
A JSON object containing the Type: JSON |
users required |
An array of JSON objects containing all params for an individual user. Type: JSON |
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: |
Given the mutil-key approach to the users
object, each element of this object is documented below:
Name | Description |
---|---|
email optional |
Email address(es) for the user. Type: Array[String] |
phone optional |
Phone number(s) for the user. Type: Array[String] |
device_id optional |
IDFA/AdID/Android ID Type: Array[String] |
twitter_handle optional |
The @handle(s) belonging to the user Type: Array[String] |
twitter_id optional |
The Twitter ID belonging to the user Type: Array[String] |
Example Request¶
POST https://ads-api.twitter.com/4/accounts/18ce54d4x5t/tailored_audiences/1nmth/users
[
{
"operation_type": "Update",
"params": {
"effective_at": "2018-05-15T00:00:00Z",
"expires_at": "2019-01-01T07:00:00Z",
"users": [
{
"email": [
"4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
],
"phone_number": [
"34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
"815d1329cc82c1bb915dbe9d5ad489ff5c6b8322370f95d03e4cca4fcf4590af"
]
},
{
"email": [
"5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
],
"phone_number": [
"34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
"00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
]
}
]
}
},
{
"operation_type": "Delete",
"params": {
"effective_at": "2018-05-15T00:00:00Z",
"expires_at": "2019-01-01T07:00:00Z",
"users": [
{
"device_id": [
"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
],
"email": [
"4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
],
"handle": [
"461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
],
"phone_number": [
"34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
"815d1329cc82c1bb915dbe9d5ad489ff5c6b8322370f95d03e4cca4fcf4590af"
],
"twitter_id": [
"c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
]
},
{
"email": [
"5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
],
"phone_number": [
"858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
"bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
]
}
]
}
}
]
Example Response¶
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"tailored_audience_id": "1nmth"
}
},
"data": {
"success_count": 4,
"total_count": 4
}
}