> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audiences API Reference

> Endpoint reference for the X Ads Audiences API, including keyword insights, custom audience management, and user list upload request and response details.

## API Reference

### Keyword Insights

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET insights/keywords/search[](#get-insights-keywords-search "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="granularity" type="enum" required>
  Specifies the granularity of the data returned for the time range denoted by `start_time` and `end_time`. For instance, when set to `HOUR`, you will be presented with a datapoint for each hour between `start_time` and `end_time`.<br /><br />
  Possible values: `DAY`, `HOUR`
</ParamField>

<ParamField query="keywords" type="string" required>
  A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.<br /><br />
  **Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
</ParamField>

<ParamField query="start_time" type="string" required>
  Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField query="end_time" type="string" optional>
  Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />
  **Note**: Defaults to the current time.
</ParamField>

<ParamField query="location" type="string" optional>
  A targeting value you would get from the [GET targeting\_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations) endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.
</ParamField>

<ParamField query="negative_keywords" type="string" optional>
  A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.<br /><br />
  **Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```json theme={null}
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[](#example-response "Permalink to this headline")**\*

```
    {
      "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

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

#### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="tailored_audience_id" type="string" required>
  A reference to the tailored audience you are operating with in the request.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="granted_account_ids" type="string" optional>
  Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="tailored_audience_permission_ids" type="string" optional>
  Scope the response to just the desired tailored audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="granted_account_id" type="string" required>
  The account you wish to grant the tailored audience permissions for.
</ParamField>

<ParamField query="permission_level" type="enum" required>
  The type of access to the tailored audience that the `granted_account_id` should have.<br /><br />
  Possible values: `READ_ONLY`, `READ_WRITE`
</ParamField>

<ParamField path="tailored_audience_id" type="string" required>
  A reference to the tailored audience you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#delete-accounts-account-id-tailored-audiences-tailored-audience-id-permissions-tailored-audience-permission-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="tailored_audience_id" type="string" required>
  A reference to the tailored audience you are operating with in the request.
</ParamField>

<ParamField path="tailored_audience_permission_id" type="string" required>
  A reference to the tailored audience permission you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/targeted[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "Permalink to this headline")

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField query="with_active" type="boolean" default="true">
  When `false`, includes line items that have `servable=false` status.
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Permalink to this headline")

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](/x-ads-api/audiences/reference#twitter-user-id-normalization).

**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[](#resource-url "Permalink to this headline")

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

#### Parameters[](#parameters "Permalink to this headline")

<ParamField query="operation_type" type="enum" required>
  The per `users` group operation type being performed.<br /><br />
  Possible values: `Update`, `Delete`
</ParamField>

<ParamField query="params" type="object" required>
  A JSON object containing the `users` array, the `effective_at` and `expires_at` timestamps.
</ParamField>

<ParamField query="users" type="array" required>
  An array of JSON objects containing all params for an individual user.
</ParamField>

<ParamField query="effective_at" type="string" optional>
  The UTC time at which the custom audience association(s) should take effect. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to the current date and time.
</ParamField>

<ParamField query="expires_at" type="string" 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](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from the request timestamp.
</ParamField>

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

<ParamField query="email" type="array" optional>
  Email address(es) for the user.
</ParamField>

<ParamField query="device_id" type="array" optional>
  IDFA/AdID/Android ID.
</ParamField>

<ParamField query="handle" type="array" optional>
  The @handle(s) belonging to the user.
</ParamField>

<ParamField query="twitter_id" type="array" optional>
  The X ID belonging to the user.
</ParamField>

<ParamField query="phone_number" type="array" optional>
  Phone number(s) for the user.
</ParamField>

<ParamField query="partner_user_id" type="array" optional>
  The user's ID in the partners' system.
</ParamField>

#### Example Request[](#example-request "Permalink to this headline")

`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[](#example-response "Permalink to this headline")

```
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }
```

### Custom Audience Permissions

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="granted_account_ids" type="string" optional>
  Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="custom_audience_permission_ids" type="string" optional>
  Scope the response to just the desired custom audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="granted_account_id" type="string" required>
  The account you wish to grant the custom audience permissions for.
</ParamField>

<ParamField query="permission_level" type="enum" required>
  The type of access to the custom audience that the `granted_account_id` should have.<br /><br />
  Possible values: `READ_ONLY`, `READ_WRITE`
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#delete-accounts-account-id-custom-audiences-custom-audience-id-permissions-custom-audience-permission-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField path="custom_audience_permission_id" type="string" required>
  A reference to the custom audience permission you are operating with in the request.
</ParamField>

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField path="custom_audience_permission_id" type="string" required>
  A reference to the custom audience permission you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/custom\_audiences[](#get-accounts-account-id-custom-audiences "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="permission_scope" type="enum" default="OWNER">
  Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own.<br /><br />
  Possible values: `OWNER`, `SHARED`
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope resource by `name`.<br /><br />
  **Note**: This performs case-insensitive prefix matching.<br /><br />
  Min, Max length: `1`, `255`
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="custom_audience_ids" type="string" optional>
  Scope the response to just the desired custom audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#get-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")

Retrieve specific Custom Audiences associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#post-accounts-account-id-custom-audiences "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="name" type="string" required>
  The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
</ParamField>

<ParamField query="description" type="string" optional>
  A description for this audience.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#put-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")

Update the specific Custom Audience associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the Custom Audience you are operating with in the request.
</ParamField>

<ParamField query="name" type="string" optional>
  The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
</ParamField>

<ParamField query="description" type="string" optional>
  A description for this audience.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#post-batch-accounts-account-id-custom-audiences "Permalink to this headline")

Allows for batch creation of Custom Audiences. See the [Custom Audiences Overview](/x-ads-api/audiences) 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**

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

* 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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="audience_type" type="enum" required>
  The type of audience to create.<br /><br />
  Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE`
</ParamField>

<ParamField query="child_segments" type="array" required>
  An array containing objects which define the subset of a Custom Audience's members that you would like to target. Each object should contain a `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate`, and, in some cases, additional `child_segments`.
</ParamField>

<ParamField query="name" type="string" required>
  The display name for the audience. Unique name value must be used. Failure to do so will result in an error.
</ParamField>

<ParamField query="operation_type" type="enum" required>
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Update`, `Delete`
</ParamField>

<ParamField query="boolean_operator" type="enum" optional>
  The logical relationship between the child segments in its parent (containing) object. Required if child\_segments is non-empty for the parent object.<br /><br />
  Possible values: `AND`, `OR`
</ParamField>

<ParamField query="lookback_window" type="int" optional>
  An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience.<br /><br />
  Possible values: `1`, `7`, `14`, `30`
</ParamField>

<ParamField query="segments" type="object" optional>
  An object containing a `boolean_operator` and `child_segments` which define the subset of a Custom Audience's members that you would like to target.
</ParamField>

<ParamField query="custom_audience_id" type="string" optional>
  The id of the custom audience to use as a child segment.
</ParamField>

<ParamField query="frequency" type="int" default="1">
  An integer value specifying the frequency within the lookback window that the user has taken the specific action and qualified for the given custom audience.
</ParamField>

<ParamField query="frequency_comparator" type="string" default="NUM_GTE">
  The comparator to the `frequency` passed in the request.<br /><br />
  **Note**: In the values below, `GTE` refers to greater than or equal, `LT` to less than, and so on.<br /><br />
  Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT`
</ParamField>

<ParamField query="negate" type="boolean" default="true">
  Negates the segment and thus is excluded in the combination.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```
    {
      "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-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline")

Delete the specified Custom Audience belonging to the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="custom_audience_id" type="string" required>
  A reference to the custom audience you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#post-accounts-account-id-do-not-reach-lists "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="description" type="string" optional>
  A description for this audience.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalink to this headline")

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](/x-ads-api/audiences/reference#e-mail-normalization).

**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[](#resource-url "Permalink to this headline")**

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

<ParamField query="operation_type" type="enum" required>
  The per item operation type being performed.<br /><br />
  Possible values: `Update`, `Delete`
</ParamField>

<ParamField query="params" type="object" required>
  A JSON object containing the `emails` array and the `expires_at` timestamp.
</ParamField>

<ParamField query="emails" type="array" required>
  An array of hashed email addresses.
</ParamField>

<ParamField query="expires_at" type="string" required>
  The UTC time at which the Do Not Reach List association(s) should expire. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="do_not_reach_list_id" type="string" required>
  A reference to the Do Not Reach List you are operating with in the request.
</ParamField>

<ParamField query="operation_type" type="enum" required>
  The per `users` group operation type being performed.<br /><br />
  Possible values: `Update`, `Delete`
</ParamField>

<ParamField query="params" type="object" required>
  A JSON object containing the `emails` array and `expires_at` timestamp.
</ParamField>

<ParamField query="users" type="array" required>
  An array of JSON objects containing all params for an individual user.
</ParamField>

<ParamField query="expires_at" type="string" 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](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from current timestamp.
</ParamField>

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

<ParamField query="email" type="array" optional>
  Email address(es) for the user.
</ParamField>

<ParamField query="phone_number" type="array" optional>
  Phone number(s) for the user.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

```
`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[](#example-response "Permalink to this headline")**

```
    {
      "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-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

None

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

```
    {
      "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
      }
    }
```