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