> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-810351b9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Audiences API Reference
> Complete technical reference for all Audiences endpoints in the X Ads API — Tailored Audiences, Custom Audiences, Audience Permissions, Users in Audiences, Keyword Insights, Do Not Reach Lists, and targeting permissions.
## API Reference
### Keyword Insights
#### 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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| granularity *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`. request.
Type: enum
Possible values: `DAY`, `HOUR` |
| keywords *required* | A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.
**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
Type: string
Example: `developers` |
| start\_time *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).
Type: string
Example: `2017-07-10T00:00:00Z` |
| end\_time *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).
**Note**: Defaults to the current time.
Type: string
Example: `2017-07-11T00:00:00Z` |
| location *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.
Type: string
Example: `0ce8b9a7b2742f7e` |
| negative\_keywords *optional* | A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.
**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
Type: string
Example: `rain` |
**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
#### 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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| tailored\_audience\_id *required* | A reference to the tailored audience you are operating with in the request.
Type: string
Example: `1nmth` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` |
| granted\_account\_ids *optional* | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `18ce54aymz3` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.
Type: string
Example: `created_at-asc` |
| tailored\_audience\_permission\_ids *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.
Type: string
Example: `ri` |
| with\_total\_count *optional* | Include the `total_count` response attribute.
**Note**: This parameter and `cursor` are exclusive.
**Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| granted\_account\_id *required* | The account you wish to grant the tailored audience permissions for.
Type: string
Example: `18ce54aymz3` |
| permission\_level *required* | The type of access to the tailored audience that the `granted_account_id` should have.
Type: enum
Possible values: `READ_ONLY`, `READ_WRITE` |
| tailored\_audience\_id *required* | A reference to the tailored audience you are operating with in the request.
Type: string
Example: `2906h` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| tailored\_audience\_id *required* | A reference to the tailored audience you are operating with in the request.
Type: string
Example: `1nmth` |
| tailored\_audience\_permission\_id *required* | A reference to the tailored audience permission you are operating with in the request.
Type: string
Example: `ri` |
**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
#### 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`
| Name | Description |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` |
| with\_active *optional* | When `false`, includes line items that have `servable=false` status
Type: boolean
Default: `true` Possible values: `true`, `false` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` |
**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
#### 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")
| Name | Description |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operation\_type *required* | The per `users` group operation type being performed.
Type: enum
Possible values: `Update`, `Delete` |
| params *required* | A JSON object containing the `users` array, the `effective_at` and `expires_at` timestamps.
Type: JSON |
| users *required* | An array of JSON objects containing all params for an individual user.
Type: JSON |
| effective\_at *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.
Type: string
Example: `2017-07-05T07:00:00Z` |
| expires\_at *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.
Type: string
Example: `2017-07-05T07:00:00Z` |
Given the mutil-key approach to the `users` object, each element of this object is documented below:
| Name | Description |
| :---------------------------------- | :--------------------------------------------------------------------- |
| email *optional* | Email address(es) for the user.
Type: Array\[String] |
| device\_id *optional* | IDFA/AdID/Android ID
Type: Array\[String] |
| handle *optional* | The @handle(s) belonging to the user
Type: Array\[String] |
| twitter\_id *optional* | The X ID belonging to the user
Type: Array\[String] |
| phone\_number *optional* | Phone number(s) for the user
Type: Array\[String] |
| partner\_user\_id *optional* | The user's ID in the partners' system.
Type: Array\[String] |
#### 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
#### 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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `1nmth` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` |
| granted\_account\_ids *optional* | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `18ce54aymz3` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
Type: string
Example: `created_at-asc` |
| custom\_audience\_permission\_ids *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.
Type: string
Example: `ri` |
| with\_total\_count *optional* | Include the `total_count` response attribute.
**Note**: This parameter and `cursor` are exclusive.
**Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| granted\_account\_id *required* | The account you wish to grant the custom audience permissions for.
Type: string
Example: `18ce54aymz3` |
| permission\_level *required* | The type of access to the custom audience that the `granted_account_id` should have.
Type: enum
Possible values: `READ_ONLY`, `READ_WRITE` |
| custom\_audience\_id *required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `1nmth` |
| custom\_audience\_permission\_id *required* | A reference to the custom audience permission you are operating with in the request.
Type: string
Example: `ri` |
**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
#### 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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` |
| permission\_scope *optional* | 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.
Type: enum
Default: `OWNER` Possible values: `OWNER`, `SHARED` |
| q *optional* | An optional query to scope resource by `name`.
**Note**: This performs case-insensitive prefix matching.
Type: string
Min, Max length: `1`, `255` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
Type: string
Example: `created_at-asc` |
| custom\_audience\_ids *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.
Type: string
Example: `1nmth` |
| with\_deleted *optional* | Include deleted results in your request.
Type: boolean
Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Include the `total_count` response attribute.
**Note**: This parameter and `cursor` are exclusive.
**Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` |
| with\_deleted *optional* | Include deleted results in your request.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| name *required* | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
Type: string
Example: `ads api users` |
| description *optional* | A description for this audience.
Type: string
Example: `Collection of all users of the Ads API` |
**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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | A reference to the Custom Audience you are operating with in the request
Type: string
Example: `2906h` |
| name *optional* | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
Type: string
Example: `ads api users` |
| description *optional* | A description for this audience.
Type: string
Example: `Collection of all users of the Ads API` |
**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**
* 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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| audience\_type *required* | The type of audience to create.
Type: enum
Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE` |
| child\_segments *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`.
Type: array |
| name *required* | The display name for the audience. Unique name value must be used. Failure to do so will result in an error.
Type: string
Example: `my_flexible_audience_name` |
| operation\_type *required* | The per item operation type being performed.
Type: enum
Possible values: `Create`, `Update`, `Delete` |
| boolean\_operator *sometimes required* | The logical relationship between the child segments in its parent (containing) object. Required if child\_segments is non-empty for the parent object.
Type: enum
Possible values: `AND`, `OR` |
| lookback\_window *sometimes required* | An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience.
Type: int
Possible values: `1`, `7`, `14`, `30` |
| segments *sometimes required* | 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.
Type: object |
| custom\_audience\_id *sometimes required* | The id of the custom audience to use as a child segment.
Type: string
Example: `tyfo` |
| frequency *optional* | 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.
Type: int
Default value: `1` |
| frequency\_comparator *optional* | The comparator to the `frequency` passed in the request.
**Note**: In the values below, `GTE` refers to greater than or equal, `LT` to less than, and so on.
Type: string
Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE` |
| negate *optional* | Negates the segment and thus is excluded in the combination.
Example: `18ce54d4x5t` |
| custom\_audience\_id *required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` |
**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
#### 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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| with\_deleted *optional* | Include deleted results in your request.
Type: boolean
Default: `false` Possible values: `true`, `false` |
**Example Request[](#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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| description *optional* | A description for this audience.
Type: string
Example: `A list of users to exclude` |
**Example Request[](#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`
**Parameters[](#parameters "Permalink to this headline")**
| Name | Description |
| :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` |
| do\_not\_reach\_list\_id *required* | A reference to the Do Not Reach List you are operating with in the request
Type: string
Example: `2906h` |
| operation\_type *required* | The per `users` group operation type being performed.
Type: enum
Possible values: `Update`, `Delete` |
| params *required* | A JSON object containing the `emails` array and `expires_at` timestamp.
Type: JSON |
| users *required* | An array of JSON objects containing all params for an individual user.
Type: JSON |
| expires\_at *optional* | The UTC time at which the user association(s) should expire. The specified time must be later than the value of the current timestamp. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from current timestamp.
Type: string
Example: `2017-07-05T07:00:00Z` |
Given the mutil-key approach to the `users` object, each element of this object is documented below:
| Name | Description |
| :------------------------------ | :-------------------------------------------------------------- |
| email *optional* | Email address(es) for the user.
Type: Array\[String] |
| phone\_number *optional* | Phone number(s) for the user
Type: Array\[String] |
**Example Request[](#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
}
}
```