Audiences

​

Custom Audiences

​

Overview

There are multiple ways for partners to create Custom Audiences.

• Audience API (CRM)
• Web
• Mobile
• Flexible

Please note that you cannot exclude lookalike custom audiences from targeting. Additionally, you cannot target both a custom audience and a custom audience lookalike on the same ad line item (ad group).

Audience management

Audiences can be managed via audience partners and Ads API partners. We offer a series of endpoints in the API to access and maintain custom audiences.

For custom audience information, we offer 2 endpoints:

• GET accounts/:account_id/custom_audiences
• GET accounts/:account_id/custom_audiences/:custom_audience_id

For more details on how to upload and manage audiences, view the Audience API guide.

Processing Times

Generally speaking audience changes are processed in batches that run every 6-8 hours. While an audience change is processing the existing audience to be updated is unaffected. We do not recommend making more than one update for additions and one update for removals per audience within this timeframe.

Targeting

An audience can only be targeted if it matches at least 100 users active within the past 90 days on X-owned and -operated clients. GET accounts/:account_id/custom_audiences/:custom_audience_id will indicate if an audience may not be targeted because it matches too few users.

Audience API (CRM)

Audience or API partners provide a list of hashed identifiers and X performs a match and produces segments that are made available against media buying on X. Partners can create these audiences with the Audience API.

How it works?

Web

We offer a standard cookie matching process when working with MPP audience partners to identify segments to target against media buying on X. In addition, advertsiers can setup a X Web Event Tag to collect website user data and create a corresponding Custom Audience.

Setup Steps

How it works?

Mobile

Please see the Custom Audiences from Mobile Apps blog post for details.

Flexible

Flexible audiences give advertisers the ability to build and save audience combinations based on existing custom audiences or subsets of existing custom audiences. Subsets of a custom audience’s members can be targeted based on the recency and frequency of interaction.

Restricted Use Cases for Custome Audiences

Read more about restrictions

​

Audiences FAQ

Q: We pushed a huge amount of data, why does the audience size show up as TOO_SMALL?

A: Currently the data is being added into audience in realtime, but the job which processes data to provide audience size will run only after a period of time. The correct audience size should be displayed in the UI after a matter of hours.

Q: We finished sending audience data, and waited 24 hours or more, but still cannot target the audience - what should we do as next steps?

A: Please confirm that the following things:

• The user ID being passed is correct and not malformed.
• The audience names being passed are correct and match previous membership updates.
• Please confirm the response from POST commands.
• Please confirm the ID Sync pixel is implemented correctly, and as described by ID Sync process enough users have visited the site in question to map users. Unmapped users in the membership updates will not be translated into targeted users.

If all else are confirmed as correct and working, please contact Twitter product contacts with information as detailed as possible (see Guide to Partner Inbounds for example of preferred information).

Q: How many times can we call the endpoint, and with what algorithm?

A: We strongly recommend that you call our system with incremental deltas, and never re-send the complete audience memberships. The system has been tested to have a throughput sufficient to process incremental data updates for some of the largest websites in the world. The initial upload of audiences should be carefully throttled and first upload is expected to take a significant amount of time to complete.

Q: What is the minimum size for an audience to be used for targeting?

• The minimum size for an audience to is 100 users (post match). If an audience with less than 500 users is matched, it will not be available for targeting in the Twitter Ads UI.

Q: How long will it take to process the audience files? And how long will it take for the audience files to be ready in the Twitter User Interface?

• It typically takes 4-6 hours to process the audience files, but that will depend on the size of the file. Once the file is processed the audiences are available on the Twitter Ads UI.

Q: How is the match rate calculated?

• Match Rate = 90 day active Twitter users / number of users provided

Q: How do we test if an audience file is working properly?

• You can provide a test audience file and use “keltonlynn” as the advertiser handle. We can then verify that the file is able to be properly ingested and loaded into the Twitter UI.

Q: What is a partner user identifier (p_user_id)?

• This is the identifier that is used by your company to uniquely identify each of your customers.

Q: What is a standard ID?

• This can be an email address, device ID, twitter @handle or ID).

Q: How do I get the HMAC Key?

• This will be provided by an encrypted email. Please provide your public PGP key to mpp-inquiry@twitter.com and we will send you a test email to verify that everything is working. Once verified, we will send you the HMAC Key.

Q: How do I verify that the hashing process worked using the given HMAC Key?

• Twitter will provide a test file (containing sample email addresses, device IDs, etc…) and a resulting hash file that you can verify your results against.

Q: Is there a file size limitation for the full data match file?

• No, there is no size limitation for the full data match file.

Q: How long will it take for the full data match file to be processed?

• Once the file is received by Twitter, it will take approximately 1 day to process the file.

​

CRM

This document describes the integration details for Custom Audiences CRM partners including file formats & data exchange process.

Summary

Company will provide a list of hashed common user identifiers (i.e. e-mail addresses) or partner user IDs on behalf of a customer to Twitter to perform a blind match and produce a list of Twitter User IDs for targeting. The segments for targeting will be made available to the advertiser’s specific @handle specified by the filename in ads.twitter.com campaign setup.

All files from Company will be provided to Twitter through a secure package on IronBox (www.golockbox.com) through a specific account granted to Company by Twitter. Twitter will provide access to IronBox. Documentation on IronBox APIs can be found at https://secure.goironcloud.com/Docs/Help/.

​

Partner ID Matching Requirements

If company uses its own standard ID system to track users (i.e. not common user identifiers like email addresses, device ids, twitter user ID, etc…) then this is the recommended process.

1. Full Data match

Initially, Company will provide a comprehensive list of all user records which include a unique common user identifier with Twitter in a single file to perform a full data match and produce a mapping stored by Twitter of Partner IDs (p_user_id) to Twitter IDs (tw_id). This will be done on a 2-3 month basis regularly to ensure proper upkeep. Once the match is completed, Twitter will share a baseline match rate from this file with Company via e-mail.

The format of this file should be:

Name Convention: FullDataMatch.[CompanyName].txt

Hashing Algorithm: HMAC_SHA-256

Format:

Column 1: HMAC hashed value of common identifiers

Column 2: Partner User ID (unique per user, non-unique in file)

Column Delimiter (CSV): Commas will be used to delimit the hashed common user identifier from the Partner ID

Line separated values

• Ex: If user record A has Partner User ID 1 and common identifier 1, 2 and 3:

*See Hashing Directions section for common user identifiers below

2. Custom Segment Lists

Company will provide lists of users in the form of p_user_id to create custom audiences for customers for targeting on Twitter.

• Line separated values
• p_user_id
• • (Same as provided in 1. Full Data Match section above. If the value provided in full data match is hashed then Company will provide same hashed value in audience file. If value provided is not hashed then Company will provide unhashed value.)

​

Standard Matching Requirements

If company does not use a standard ID for mapping of all customer user identifiers, this is the recommended process.

Custom Segment Lists

Company will provide lists of hashed common user identifiers directly to Twitter on behalf of customers to to create custom audiences.

The format of this file should be:

• Line separated values
• Hashed common user identifier (i.e. e-mail address)
• Follow file naming conventions outlined below
• Follow hashing directions for e-mail addresses below (in Hashing Directions)

​

Custom Segment List File Naming & Operations

The operation of a file will be dictated by the name of the file with the following available operations and general file naming convention: audiencename_partnername.handle.operation.filetype

• audiencename: The name of the Custom Audience. This field is the name that will be displayed when selecting the audience in the ads.twitter.com campaign setup UI e.g. brand_loyalty_card_holders.
• partnername: Name of the company delivering the data on behalf of advertiser e.g. company_name.
• handle: Twitter Account (@handle) that will have access to Custom Audiences e.g. @pepsi, @dietpepsi
• operation: new, add, remove, removeall, replace (details below)
• : Standard Unix epoch time in seconds, used to ensure that each audience file uploaded is unique
• filetype: file should be in *.txt format

​

Creating and Updating Audiences

Create a new audience with a single file e.g. loyalty_card_holders_partnername.pepsi.new.txt

Add - Add the matches from a list to an existing audience e.g. loyalty_card_holders_partnername.pepsi.add..txt

Remove - Remove the matches from a list from an existing audience Ex: loyalty_card_holders_partnername.pepsi.remove..txt

Remove All - Remove the matches produced from a regularly updated cumulative list from all audiences for that client (i.e. Client’s Opt Out List). Ex: partnername.pepsi.removeall.txt

• This can be used for a comprehensive list of users who have opted-out from the Advertiser.
• Twitter will only respect the latest list provided in this file, and will respect across all existing and future audiences for matched.

Twitter users at the time this file was provided & processed.

Replace - Remove an existing audience and replace it with a new audience list. Ex: loyalty_card_holders_partnername.pepsi.replace..txt

Overall Company Opt-Out - Company will provide a cumulative Opt-Out file to remove users that have opted out as per the Company’s Opt-Out policy.

Twitter will only respect the latest list provided in this Company Opt-Out file and will respect across all existing and future audiences for matched Twitter users at the time this file was provided & processed. The format of the Company Opt-Out file will be as follows: Ex: partnername.removeall.txt

Delete - Remove an existing audience from the current list of audiences e.g. Ex: loyalty_card_holders_partnername.pepsi.delete.txt

​

Hashing Directions

Twitter will securely share a base64 encoded production key via PGP for hashing common user identifiers (i.e. email addresses). Company will base64 decode the key to produce a 32-byte key to be used to perform the hashing.

Example base64 encoded key:

BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=

Example Base64 decoded key:

/:� TшY

Normalization: Company will perform basic normalization on the common user identifiers before hashing (except on Device IDs, see Device ID Normalization section).

​

E-mail Normalization

Namely, strip out the leading and trailing spaces and also lowercase the email address.

Ex: Raw e-mail address: testemail_Organisational_baseball+884@It92I6Ev2B.Com

After normalization: testemail_organisational_baseball+884@it92i6ev2b.com

Hashed value: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec

Note: The specific number of characters for both the encoded hmac and key could vary based on the input and the encoding so the specific number of characters.

​

Device ID Normalization

We will have the same requirements for hashing of device IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. We strip out spaces like we do with email addresses, but there is no lowercase normalization for IDFAs/Android IDs and the exact format of the IDFA/Android ID should be used.

Here is example raw format of Device IDs for iOS & Android, pre-hashing:

iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431

Android ID: b5bf2122961b3595

Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b

Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

​

Twitter User ID Normalization

Twitter IDs will still be hashed as the grouping of data - ie Customer List of @handles - is private to the advertiser even though it is not PII. We will have the same requirements for hashing of Twitter IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. Spaces should be stripped out of both the Twitter ID/@username, but User IDs do not require normalization. @usernames should be lowercased for normalization. And the @ symbol should not be included as part of the username.

The raw ID format will be:

• User ID: 27674040
• @username: testusername

Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85

Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

​

ID Sync Integration

Partners sending data with a p_id must undergo an ID Sync process to generate a mapping of the advertiser or partner’s user ids to Twitter user ids. This allows advertisers to directly target their own user segments on Twitter. Partners must also set the value of the param user_identifier_type to either TALIST_PARTNER_USER_ID or TAWEB_PARTNER_USER_ID while sending their membership updates.

• Web Only: This can be done by placing a pixel on the advertiser’s site, as outlined below.
• List: This can be done using any of the methods described on the CRM page.

​

Pixel URL

​

Pixel Parameters

​

ID Sync Pixel:

Using an example partner id of 111, and an example p_user_id of abc, the constructed pixel would be the following:

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.twitter.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

Opt-Out File Configuration and Sending Opt-Out Files

Partners should provide Twitter with a list of users that to the partner’s best knowledge have selected to opt-out of targeted ad delivery. The format of file should be sent as:

Sending Membership Updates

As specified in our endpoint documentation, when passing users via the POST custom_audience_memberships endpoint you should pass a customer ID to enable a cookie based match. Partners sending data with a p_id must set the user_identifier_type to TALIST_PARTNER_USER_ID or TAWEB_PARTNER_USER_ID.

All other steps will remain the same as those listed in the Real-Time Audience API Integration Guide

​

Custom Audiences User Data

This document outlines the format for [Custom Audience]/x-ads-api/audiences user data.

Data normalization

Device IDs:

• IDFA - lower-cased with dashes; ex: 4b61639e-47cc-4056-a16a-c8217e029462
• AdID - original format on device is required, not capitalized with dashes; ex: 2f5f5391-3e45-4d02-b645-4575a08f86e
• Android id - original format on device is required, not capitalized without dashes or spaces; ex: af3802a465767e36

Email Addresses:

• lowercase, remove leading and trailing spaces; ex: support@twitter.com

Twitter Usernames:

• no @, lowercased and leading and trailing spaces trimmed; ex: jack

Twitter User IDs:

• Standard integer; ex: 143567

Data hashing

The data for each line must be hashed using SHA256, without a salt.  Additionally, the final output hash must be in lower case. E.g., 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d and **not **49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hasing user @AdsAPI using python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Additional code samples for hashing can be found at github.com/twitterdev/ads-platform-tools.

​

Custom Audiences: Web

Information

Partners will send a list of IDs (p_user_ids) to target on behalf of an advertiser. This is accomplished through an ID Sync process that builds a mapping between the p_user_ids and Twitter user ID. This mapping is then used to produce lists of Twitter User IDs that can be used for Targeting. These custom audiences will be made available on the advertiser’s specific @handle specified by the label on ads.twitter.com Custom Audiences Web campaign setup.

Twitter will provide the secure pixel that can be dropped on partner tags and sites in order to match the IDs (p_user_ids) to Twitter user IDs. Once the ID Sync process is complete, the targeting files will be created by the partner and will be made available to Twitter through a HTTPS endpoint. These targeting files are ingested on a regular basis by Twitter and are then made available in the Twitter UI.

Twitter Secure Pixel

The Twitter secure pixel will look as follows:

https://analytics.twitter.com/i/adsct?p\_user\_id=xyz&p_id=123

p_user_id - xyz represents the partner user ID that is provided by the Partner

p_id - 123 represents the unique ID for the Partner (provided by Twitter)

Partner HTTPS Endpoint & Targeting User File

Partner will need to provide Twitter with a HTTPS endpoint and credentials (username/password) that can be used to ingest the targeting file on a regular basis. A sample HTTPS endpoint will look as follows:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - Format Code for Year (YYYY)

%M - Format Code for Month (MM)

%D - Format Code for Day (DD)

The transmitted data will consist of the following files:

1. Partner Targeting User File
2. Targeting Conversion File

All the files will be in the TSV format, where the individual fields of each row are separated from each other by a tab character. Valid field values themselves will never contain the tab character.

Allowed Twitter IP Range:

Here is the range of IPs that can be allowed for access to the Partner Endpoint.

• 199.16.156.0/22
• 199.59.148.0/22

Partner Targeting User File:

Notes:

Every time we receive a new Partner Targeting File, we expect this to be the full list of users that Partner recommends us to target, not incremental, unless otherwise agreed upon. We will agree with each partner what the frequency of delivery of this Partner Targeting File will be. If we do not receive a Partner Targeting File as expected, we will use the previous version with some pre-defined expiration time.

​

Audience API Integration

​

Overview

The Audience API was launched as part of v4 of the Ads API and with it, brings several improvements to the legacy Audiences endpoints. This new endpoint is backed by a new Audience processing backend, and brings several improvements in terms of stability, robustness and reliability. The purpose of this guide is to highlight the differences between the Audience API and the legacy Audience upload and management processes. 

Reference documentation can be found on the Audience API reference documentation page. 

Note: All Audience user data must be SHA-256 hashed prior to upload. More details, along with the accepted user identifier types and data normalization can be found on the user data page.

Changes to Audience Functionality

The following changes to Custom Audiences have been introduced as of v4 and any deprecated endpoints will no longer be available once v3 of the Ads API has been sunset:

• Deprecated TON Upload:
  • GET accounts/:account_id/custom_audience_changes
  • GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
  • POST accounts/:account_id/custom_audience_changes
  • PUT accounts/:account_id/custom_audiences/global_opt_out
• Deprecated Real Time Audiences:
  • POST custom_audience_memberships
• Custom Audience:
  • The list_type parameter will be removed from the request and response on all Custom Audience endpoints. This parameter was previously used to identify the user identifier type of the Audience (i.e., email, Twitter User ID, etc.) however Audiences now have the ability to accept multiple user identifiers for the same Audience thereby making this value irrelevant.
• General:
  • The Audience lookback window has been updated to match against users active within the past 90 days (from 30 days)
  • The minimum number of matched users required for an audience to be targetable has been decreased to 100 users (from 500 users)

Audience Upload Process

The following table lists the primary differences between the old and new Audience creation flows, with more details available further below:

Note Any audiences being updated or opted-out via the TON Upload path must have a corresponding list uploaded via the TON Upload endpoint and associated with an Audience using the custom_audience_changes endpoint.

Rate Limiting

The Audience API endpoint has a rate limit of 1500/1min per account. There are no limits on the number of users that can be sent in a single payload. The only constraints on the payload are:

1. Total number of operations: 2500 operations

2. Maximum payload size: 5,000,000 bytes

Audience User Management

In order to create a new Audience, the following steps are required

​

Create a new Custom Audience

Create a new Custom Audience “shell” using the [POST custom_audience]/x-ads-api/audiences endpoint and retrieve the corresponding Custom Audience id. This step is required if creating an Audience from scratch. If updating an existing Audience, skip to the next section

​

Add Users to an Audience

Use the POST accounts/:account_id/custom_audiences/:custom_audience_id/users with the Custom Audience id and a sample payload like so:

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

    # All values must be hashed, unhashed values are used in this example for illustrative purposes
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@twitter.com"
              ],
              "handle": [
                "twitter",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@twitter.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

In order to add a user to an Audience, use the operation_type Update. The new Audience interface enables the ability to pass in multiple user keys for a single user. Each object in the array of JSON objects corresponds to a single user. Using the example payload above, the request will add two users to an Audience, one with an email and handle and another with an email and twitter_id. 

​

Remove Users from an Audience

Similar to the process outlined for adding users, users can be removed from an audience using like so:

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

    # All values must be hashed, unhashed values are used in this example for illustrative purposes
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@twitter.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@twitter.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

The operation_type must be set to Delete and users will be matched on any keys that were present when adding users to the audience. For example, if a user was added to an audience using an email and twitter_id, then the same user can be removed using any one of these keys, i.e., either email or twitter_id or both.

Additionally, it is possible to add and remove users from an Audience within the same request. The endpoint supports multiple operation_type per request.

​

Opt-Out Users

With the deprecation of the global opt-out endpoint, partners are required to Delete any users that have opted-out of any Audiences. There are a few ways to achieve this:

1. Keep track of which users are part of which Audiences and remove these users individually from each Audience.
2. Remove the user from all Audiences associated with an Ads account.

General Best Practices

• We strongly recommend calling this endpoint in near real-time batches to avoid spiky queues which take longer to process and in general cause unnecessary load on our system. This also ensures users are available for campaign targeting sooner.
• A successful API call will return a success_count and total_count corresponding to the number of user objects that have been received in the request.
• This endpoint is atomic in nature, that is, either the entire request is successful or in case of any errors then the entire request will fail. In case of an error response, consumers of the API are recommended to fix the error and retry the request with the entire payload. 
• Upon failure, partners recommended to use an exponential backoff approach with retries. For example, retry immediately upon the first failure, retry after 1 minute after the second failure and retry after 5 minutes after the third consecutive failure, and so on

​

API Reference

​

Keyword Insights

​

GET insights/keywords/search

Given a group of keywords, get the associated Tweet volume as well as a set of 30 related keywords. The Tweet volume corresponds to the input keywords only, not the related keywords.

A maximum time range (end_time - start_time) of 7 days is allowed.

Please note that results are scoped by a single geo (country).

Resource URL

https://ads-api.x.com/12/insights/keywords/search

Parameters

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

Example Response*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

​

Tailored Audience Permissions

​

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Retrieve details for some or all permissions associated with the specified tailored audience.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Parameters

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Create a new permission object allowing the specified audience to be shared with a given account.

Note: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the is_owner response attribute in the response for a given audience.

Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS account feature.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Parameters

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Revoke the specified Tailored Audience sharing permission.

Note: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the is_owner response attribute in the response for a given audience.

When revoked, we guarantee that the granted account (granted_account_id) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Parameters

Example Request

DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

​

Targeted Audiences

​

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Retrieve a list of active or all line items and campaigns that target a given custom_audience_id

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "test-campaign",
          "line_items": [
            {
              "id": "5gzog",
              "name": "test-line-item",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Untitled campaign",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

​

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

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

​

Custom Audience Permissions

​

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Retrieve details for some or all permissions associated with the specified custom audience.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Parameters

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

​

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Create a new permission object allowing the specified audience to be shared with a given account.

Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the is_owner response attribute in the response for a given audience.

Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS account feature.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Parameters

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Revoke the specified Custom Audience sharing permission.

Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the is_owner response attribute in the response for a given audience.

When revoked, we guarantee that the granted account (granted_account_id) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Parameters

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

​

Custom Audiences

​

GET accounts/:account_id/custom_audiences

Retrieve details for some or all Custom Audiences associated with the current account.

Resource URL

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

Parameters

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth

Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

​

GET accounts/:account_id/custom_audiences/:custom_audience_id

Retrieve specific Custom Audiences associated with the current account.

Resource URL

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

Parameters

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h

Example Response

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

​

POST accounts/:account_id/custom_audiences

Create a new placeholder Custom Audience associated with the current account.

Resource URL

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

Parameters

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

​

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Update the specfic Custom Audience associated with the current account.

Resource URL

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

Parameters

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

​

POST batch/accounts/:account_id/custom_audiences

Allows for batch creation of Custom Audiences. See the Custom Audiences Overview page for information on audiences.

Note: This batch endpoint is currently in closed beta and available to select advertisers. During this beta period, only Flexible Audiences based on mobile custom audiences can be created.

Batch Requests

• The current maximum batch size is 10.
• 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

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

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 parameter) are shown in the response under the operation_errors object.

Flexible Audiences

• Flexible Audiences are immutable once created.
• Custom Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences
• A maximum of 10 Custom Audiences leaf nodes can be used to create a Flexible Audience.

Resource URL

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

Parameters

Example Request

POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Example Response

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

​

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Delete the specified Custom Audience belonging to the current account.

Resource URL

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

Parameters

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h

Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

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