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 the operation_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 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.
  • 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 users group operation type being performed.

Type: enum

Possible values: Update, Delete
params
required

A JSON object containing the users array, the effective_at and expires_at timestamps.

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

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