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
}
}