Update October 27: As a part of Ads API v12, we are introducing support for phone number as a new user identifier that can be used for matching users within Do Not Reach Lists. See updated post below for full details.**
Introducing Do Not Reach Lists
In Q1 2022, we released a new set of do_not_reach_lists endpoints.
These endpoints enable you to use Do Not Reach Lists to exclude a single group of people from all campaigns within your ads account.
Key features:
-
Exclusion Made Easy: Once a Do Not Reach List is created, it is automatically applied to all campaigns in an ads account. This means no extra steps during campaign creation and no retroactive edits on existing campaigns.
-
Enabling Responsibility: By excluding people from all campaigns within an ads account, Do Not Reach Lists enable advertisers to fully respect obligations to customer choices and industry standards.
How it works
Leveraging this endpoint, advertisers can upload a list of consumer emails or phone numbers* o create a Do Not Reach List. Uploaded user identifiers are then matched against a dataset of all active Twitter users to create the Do Not Reach List.
Once the Do Not Reach List is created & marked as “Ready” (targetable: true on the API), all campaigns within the associated ads account will automatically exclude the people in the Do Not Reach List - preventing them from receiving ads from that account.
*Phone number matching is only supported with Ads API v12 and above.
Who is this for?
This is primarily for developers providing campaign management, audiences, or targeting services.
Requirements and documentation:
As you leverage this new endpoint, keep in mind the below:
-
An Ads account ID can only have at most one Do Not Reach List. However, once created, a DNRL can be edited, updated, or deleted.
-
Users added to this list must have an expires_at timestamp set to less than 13 months from the current timestamp.
-
The Do Not Reach Lists API does not accept an effective_at timestamp and defaults to the current timestamp
-
Do Not Reach Lists do not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account.
-
For the DNRL endpoint, emails (emails) and phone numbers* (phone_number) are the only supported user identifier types.
Ads API v12 Update
As a part of Ads API v12, we are introducing support for phone number (phone_number) as a new user identifier that can be used for matching users within Do Not Reach Lists (do_not_reach_lists). Previously, we only offered support for email addresses (emails).
By offering support for this new identifier, advertisers will be able to leverage more of their customer data and improve their ability to exclude people from receiving their ads on Twitter.
-
Key Notes
-
For Do Not Reach Lists, phone number support will only be available with version 12 or above. However, for Custom Audiences, phone number matching is supported with v11. See the “Phone Number Matching in List Custom Audiences” forum post here.
-
The JSON POST body structure will be changing with this version. See examples of the v11 versus v12 requests below.
v11 Example Request
POST /11/batch/accounts/18ce54d4x5t/do_not_reach_lists/4ofrq/users
[
{
"operation_type": "Update",
"params": {
"effective_at": "2021-10-21T07:27:00Z",
"expires_at": "2021-12-22T00:00:00Z",
"emails": [
"FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC",
"CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
]
}
}
]
v12 Example Request:
POST /12/batch/accounts/18ce54d4x5t/do_not_reach_lists/4ofrq/users
[
{
"operation_type": "Update",
"params": {
"expires_at": "2023-01-22T00:00:00Z",
"users": [
{
"email": [
"FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
],
"phone_number": [
"CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
]
}
]
}
}
]
For more information on this endpoint, visit this page.
Please let us know if you have any feedback.
Twitter Ads API team
