Custom Audiences
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

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

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