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¶

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¶

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¶

Given the mutil-key approach to the users object, each element of this object is documented below:

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