Audiences API Reference

API Reference

Keyword Insights

GET insights/keywords/search

Given a group of keywords, get the associated Tweet volume as well as a set of 30 related keywords. The Tweet volume corresponds to the input keywords only, not the related keywords. A maximum time range (end_time - start_time) of 7 days is allowed. Please note that results are scoped by a single geo (country). Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

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

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

Example Response*

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

Tailored Audience Permissions

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

Retrieve details for some or all permissions associated with the specified tailored audience. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

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. 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 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 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 GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Example Response

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

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

Create a new permission object allowing the specified audience to be shared with a given account. Note: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the is_owner response attribute in the response for a given audience. Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS account feature. Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

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

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

Example Response

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

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

Revoke the specified Tailored Audience sharing permission. Note: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the is_owner response attribute in the response for a given audience. When revoked, we guarantee that the granted account (granted_account_id) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. Resource URL

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

Parameters

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. 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 DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri Example Response

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

Targeted Audiences

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

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

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. 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 for more information. Type: string Example: `8x7v00oow`

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

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

Custom Audiences Users

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

This endpoint will allow partners to add, update and remove users from a given custom_audience_id. The endpoint will also accept multiple user identifier types per user as well. All data being provided in the users field of the request except partner_user_id must be hashed using SHA256 and normalized. Batch Requests

The current maximum batch size is 2500 for this endpoint. The batch size is determined by the number of operations (Update/Delete) per request. For example, over 2500 operation objects ({"operation_type": "Update/Delete", [..] }) in one array result in an error.
The max request POST body size this endpoint can accept is 5,000,000 bytes.
The rate limits for this endpoint are 1500 per 1 minute window
All parameters are sent in the request body and a Content-Type of application/json is required.
Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses The response returned by the Ads API contains two fields, a success_count and a total_count. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is not equal the success_count and total_count should be treated as an error condition, requiring a retry. Batch Errors

Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
Item-level errors (eg. missing required parameters) are show in the response under the operation_errors object.
The index of the error in the operation_errors refers to the index in the input item, with the corresponding error message

Resource URL

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

Parameters

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

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

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

Example Response

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

Custom Audience Permissions

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

Retrieve details for some or all permissions associated with the specified custom audience. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

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. 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 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 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 GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Example Response

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

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

Create a new permission object allowing the specified audience to be shared with a given account. Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the is_owner response attribute in the response for a given audience. Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS account feature. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

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

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

Example Response

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

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

Revoke the specified Custom Audience sharing permission. Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the is_owner response attribute in the response for a given audience. When revoked, we guarantee that the granted account (granted_account_id) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. Resource URL

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

Parameters

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. 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 DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Example Response

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

Custom Audiences

GET accounts/:account_id/custom_audiences

Retrieve details for some or all Custom Audiences associated with the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

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. 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 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 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 GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

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

GET accounts/:account_id/custom_audiences/:custom_audience_id

Retrieve specific Custom Audiences associated with the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

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. 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 GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

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

POST accounts/:account_id/custom_audiences

Create a new placeholder Custom Audience associated with the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

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. 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 POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers Example Response

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

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Update the specific Custom Audience associated with the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

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. 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 PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed Example Response

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

POST batch/accounts/:account_id/custom_audiences

Allows for batch creation of Custom Audiences. See the Custom Audiences Overview page for information on audiences. Note: This batch endpoint is currently in closed beta and available to select advertisers. During this beta period, only Flexible Audiences based on mobile custom audiences can be created. Batch Requests

The current maximum batch size is 10.
All parameters are sent in the request body and a Content-Type of application/json is required.
Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

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

Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
Item-level errors (eg. missing required parameter) are shown in the response under the operation_errors object.

Flexible Audiences

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

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

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. 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. Type: boolean Default value: `true` Possible values: `true`, `false`

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

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

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

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

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Example Response

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

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

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

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

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

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

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

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Delete the specified Custom Audience belonging to the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

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. 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`

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

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

Do Not Reach Lists

GET accounts/:account_id/do_not_reach_lists

Retrieve details for some or all Do Not Reach List associated with the current account. Note: An account_id can only have at most one Do Not Reach List Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

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. 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 GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Do Not Reach List",
          "description": "test DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/do_not_reach_lists

Create a new Do Not Reach List associated with the current account. Note: An account_id can only have at most one Do Not Reach List Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

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. 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 POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude Example Response

    {
      "request": {
        "params": {
          "description": "A list of users to exclude",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": "A list of users to exclude",
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

This endpoint allows users to be added, updated and removed from a given do_not_reach_list_id. This endpoint only accepts emails as the valid user identifier type. All data being provided in the emails field of the request must be hashed using SHA256 and normalized. Notes

An account_id can only have at most one Do Not Reach List
Users added to this list must have an expires_at timestamp set to less than 13 months from the current timestamp
Do Not Reach List API does not accept an effective_at timestamp and defaults to the current timestamp
Do Not Reach List does not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account

Batch Requests

The current maximum batch size is 2500 for this endpoint. The batch size is determined by the number of operations (Update/Delete) per request. For example, over 2500 operation objects ({"operation_type": "Update/Delete", [..] }) in one array result in an error.
The max request POST body size this endpoint can accept is 5,000,000 bytes.
The rate limits for this endpoint are 1500 per 1 minute window
All parameters are sent in the request body and a Content-Type of application/json is required.
Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
Item-level errors (eg. missing required parameters) are show in the response under the operation_errors object.
The index of the error in the operation_errors refers to the index in the input item, with the corresponding error message

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

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

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

Example Response

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Delete the specified Do Not Reach List belonging to the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id Parameters None Example Request DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp Example Response

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }

​API Reference

​Keyword Insights

​GET insights/keywords/search

​Tailored Audience Permissions

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

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

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

​Targeted Audiences

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

​Custom Audiences Users

​POST accounts/:account_id/custom_audiences/:custom_audience_id/users

​Resource URL

​Parameters

​Example Request

​Example Response

​Custom Audience Permissions

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

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

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

​Custom Audiences

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​Do Not Reach Lists

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

​POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

API Reference

Keyword Insights

GET insights/keywords/search

Tailored Audience Permissions

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

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

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

Targeted Audiences

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

Custom Audiences Users

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

Resource URL

Parameters

Example Request

Example Response

Custom Audience Permissions

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

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

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

Custom Audiences

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Do Not Reach Lists

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id