Custom Audiences Users
custom-audience-users

Custom Audiences Users

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

This endpoint will allow partners to add, update and remove users from a given custom_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 except partner_user_id 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 operations (Update/Delete) per request. For example, over 2500 operation objects ({"operation_type": "Update/Delete", [..] }) in one array result in an error.
  • The max request POST body size this endpoint can accept is 5,000,000 bytes.
  • The rate limits for this endpoint are 1500 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.x.com/12/accounts/:account_id/custom_audiences/:custom_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 custom 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 custom audience association(s) should expire. The specified time must be later than the value of effective_at. Expressed in ISO 8601. Defaults to 13 months from the request timestamp.

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]

device_id
optional

IDFA/AdID/Android ID

Type: Array[String]

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]

phone_number
optional

Phone number(s) for the user

Type: Array[String]

partner_user_id
optional

The user's ID in the partners' system.

Type: Array[String]

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

[
  {
    "operation_type": "Update",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
          ],
          "handle": [
            "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
            "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
          ]
        },
        {
          "email": [
            "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
          ],
          "twitter_id": [
            "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"
          ],
          "twitter_id": [
            "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
          ]
        },
        {
          "email": [
            "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
          ],
          "twitter_id": [
            "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
            "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
          ]
        }
      ]
    }
  }
]

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "custom_audience_id": "1nmth"
    }
  },
  "data": {
    "success_count": 4,
    "total_count": 4
  }
}