Audiences

Tailored Audiences

GET accounts/:account_id/tailored_audiences

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

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/tailored_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
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_ids
optional

Scope the response to just the desired tailored 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 will be ignored if cursor is specified.

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.twitter.com/3/accounts/18ce54d4x5t/tailored_audiences?tailored_audience_ids=1nmth

Example Response

{
  "request": {
    "params": {
      "tailored_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",
      "permission_level": "READ_WRITE",
      "is_owner": true,
      "id": "1nmth",
      "reasons_not_targetable": [],
      "list_type": "TWITTER_ID",
      "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/tailored_audiences/:tailored_audience_id

Retrieve specific Tailored Audiences associated with the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/tailored_audiences/:tailored_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
tailored_audience_id
required

A reference to the tailored 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.twitter.com/3/accounts/18ce54d4x5t/tailored_audiences/2906h

Example Response

{
  "request": {
    "params": {
      "tailored_audience_id": "2906h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "targetable": false,
    "name": "developers",
    "targetable_types": [
      "CRM",
      "EXCLUDED_CRM"
    ],
    "audience_type": "CRM",
    "permission_level": "READ_WRITE",
    "is_owner": true,
    "id": "2906h",
    "reasons_not_targetable": [],
    "list_type": "TWITTER_ID",
    "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/tailored_audiences

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

Use the POST accounts/:account_id/tailored_audience_changes endpoint to add, remove, or replace audience members based on an uploaded audience file.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/tailored_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.

Type: string

Example: ads api users
list_type
required

The type of list for this audience.

Type: enum

Possible values: DEVICE_ID, EMAIL, HANDLE, PHONE_NUMBER, TWITTER_ID, TWITTER_COOKIE_ID

Example Request

POST https://ads-api.twitter.com/3/accounts/18ce54d4x5t/tailored_audiences?name=developers&list_type=TWITTER_ID

Example Response

{
  "data": {
    "targetable": false,
    "name": "developers",
    "targetable_types": [
      "CRM",
      "EXCLUDED_CRM"
    ],
    "audience_type": "CRM",
    "permission_level": "READ_WRITE",
    "is_owner": true,
    "id": "2906h",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "list_type": "TWITTER_ID",
    "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",
      "list_type": "TWITTER_ID"
    }
  }
}

POST batch/accounts/:account_id/tailored_audiences

Allows for batch creation of Tailored Audiences. See the Tailored 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 tailored 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.
  • Tailored Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences
  • A maximum of 10 Tailored Audiences leaf nodes can be used to create a Flexible Audience.

https://ads-api.twitter.com/3/batch/accounts/:account_id/tailored_audiences

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 Tailored Audience’s members that you would like to target. Each object should contain a tailored_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.

Type: string

Example: my_flexible_audience_name
operation_type
required

The per item operation type being performed.

Type: enum

Possible values: Create, Update, Delete
params
required

A JSON object containing all params for the Campaign object.

Type: string

Example: start_time: 2017-07-05T00:00:00Z
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 tailored 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 Tailored Audience’s members that you would like to target.

Type: object
tailored_audience_id
sometimes required

The id of the tailored 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 tailored 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

POST https://ads-api.twitter.com/3/batch/accounts/18ce54d4x5t/tailored_audiences

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

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

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

                ]
              }
            ]
          }
        ]
      }
    }
  }
]

{
  "data": {
    "targetable": false,
    "name": "my_flexible_audience_name",
    "targetable_types": [
      "FLEXIBLE",
      "EXCLUDED_FLEXIBLE"
    ],
    "audience_type": "FLEXIBLE",
    "id": "13ld7",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "list_type": null,
    "metadata": [
      {
        "tailored_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": [
            {
              "tailored_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": [
                {
                  "tailored_audience_id": "txr1",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [

                  ]
                },
                {
                  "tailored_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": [
            {
              "tailored_audience_id": "TYIF",
              "lookback_window": 30,
              "frequency": 1,
              "frequency_comparator": "NUM_GT",
              "negate": true,
              "child_segments": [

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

                  ]
                },
                {
                  "tailored_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/tailored_audiences/:tailored_audience_id

Delete the specified Tailored Audience belonging to the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/tailored_audiences/:tailored_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
tailored_audience_id
required

A reference to the tailored audience you are operating with in the request.

Type: string

Example: 2906h

Example Request

DELETE https://ads-api.twitter.com/3/accounts/18ce54d4x5t/tailored_audiences/2906h

Example Response

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