Do Not Reach Lists
do-not-reach-lists

Do Not Reach Lists

GET accounts/:account_id/do_not_reach_lists

Retrieve details for some or all Do Not Reach List associated with the current account.

Note: An account_id can only have at most one Do Not Reach List

Resource URL

https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54bgxky"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "targetable": false,
      "name": "Do Not Reach List",
      "description": "test DNRL",
      "id": "4kzrq",
      "reasons_not_targetable": [
        "TOO_SMALL"
      ],
      "created_at": "2021-10-28T22:09:29Z",
      "list_size": null,
      "updated_at": "2021-11-04T03:33:06Z",
      "deleted": false
    }
  ]
}

POST accounts/:account_id/do_not_reach_lists

Create a new Do Not Reach List associated with the current account.

Note: An account_id can only have at most one Do Not Reach List

Resource URL

https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

description
optional

A description for this audience.

Type: string

Example: A list of users to exclude

Example Request

POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude

Example Response

{
  "request": {
    "params": {
      "description": "A list of users to exclude",
      "account_id": "18ce54bgxky"
    }
  },
  "data": {
    "targetable": false,
    "name": "Do Not Reach List",
    "description": "A list of users to exclude",
    "id": "4ofrq",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2022-02-08T23:02:48Z",
    "list_size": null,
    "updated_at": "2022-02-08T23:02:48Z",
    "deleted": false
  }
}

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

This endpoint allows users to be added, updated and removed from a given do_not_reach_list_id. This endpoint only accepts emails as the valid user identifier type.

All data being provided in the emails field of the request must be hashed using SHA256 and normalized.

Notes

  • An account_id can only have at most one Do Not Reach List
  • Users added to this list must have an expires_at timestamp set to less than 13 months from the current timestamp
  • Do Not Reach List API does not accept an effective_at timestamp and defaults to the current timestamp
  • Do Not Reach List does not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account

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/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

do_not_reach_list_id
required

A reference to the Do Not Reach List you are operating with in the request

Type: string

Example: 2906h

operation_type
required

The per users group operation type being performed.

Type: enum

Possible values: Update, Delete

params
required

A JSON object containing the emails array and expires_at timestamp.

Type: JSON

users
required

An array of JSON objects containing all params for an individual user.

Type: JSON

expires_at
optional

The UTC time at which the user association(s) should expire. The specified time must be later than the value of the current timestamp. Expressed in ISO 8601. Defaults to 13 months from current 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]

phone_number
optional

Phone number(s) for the user

Type: Array[String]

Example Request

POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users

[
  {
    "operation_type": "Update",
    "params": {
      "expires_at": "2023-01-22T00:00:00Z",
      "users": [
        {
          "email": [
            "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
          ],
          "phone_number": [
            "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
          ]
        },
        {
          "email": [
            "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
          ],
          "phone_number": [
            "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
          ]
        }
      ]
    }
  }
]

Example Response

{
  "data": [
    {
      "success_count": 2,
      "total_count": 2
    }
  ],
  "request": [
    {
      "params": {
        "do_not_reach_list_id": "4ofrq",
        "expires_at": "2023-01-22T00:00:00Z",
        "account_id": "18ce54bgxky"
      },
      "operation_type": "Update"
    }
  ]
}

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Delete the specified Do Not Reach List belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Parameters

None

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp

Example Response

{
  "request": {
    "params": {
      "do_not_reach_list_id": "4ofrp",
      "account_id": "18ce54bgxky"
    }
  },
  "data": {
    "targetable": false,
    "name": "Do Not Reach List",
    "description": null,
    "id": "4ofrp",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2022-02-08T23:02:07Z",
    "list_size": null,
    "updated_at": "2022-02-08T23:02:21Z",
    "deleted": true
  }
}