custom-audiences

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

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 specfic Custom Audience associated with the current account.

Resource URL¶

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

Parameters¶

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

Run in Postman ❯

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

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