Composite Audiences

This article describes resources and services that enable you to read, create, and update composite audiences.

Overview

A composite audience enables you to build and target custom audiences that are based on a combination of first-party data, third-party data, and Oath data.

You can use the following types of data to build a composite audience:

Custom Audience
An audience you build using advertiser-owned retargeting rules, conversion rules, device IDs, or anonymized email addresses.
Yahoo Audience
An audience you build using Yahoo-owned data and your own search keywords, mail domains, and purchase receipts.
Yahoo Packaged
An audience you build using predefined segments that Yahoo configures and packages. Yahoo packaged audiences come from Yahoo’s mail, marketing, political and user interest categories.
Third Party
An audience you build using your third-party data. Most data management platforms (DMPs) are integrated with the Oath Ad Platforms DSP.

Hierarchy

A Composite audience can be defined at either the seat-level or advertiser-level.

  • Seat-level audiences are shared by every advertiser account in the seat.
  • Advertiser-level audiences are specific to a single advertiser account.

Endpoint

/traffic/audiences/composite
  • Use the GET method to read an existing composite audience.
  • Use the POST method to create a new composite audience.
  • Use the PUT method to update an existing composite audience.

A composite audience is comprised of multiple audiences. Use the search segment resource to identify audiences that can be included in composite audiences.

/traffic/audiences/composite/search

To learn more, see Search Audiences.

Resources

Composite Audience Object

The Composite audience object contains the following fields:

Table 24 Composite Audience Fields
Field Description Data Type Create Update
id Specifies the audience ID. integer N/A Required
name Specifies the name of the audience. string Required Optional
status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: the audience can be targeted.
  • INACTIVE: the audience cannot be targeted.
[1]If not specified when creating the audience, defaults to ACTIVE.
string Optional [1] Optional
accountId

Specifies the advertiser ID.

If specified, the audience is tied to a specific advertiser and can only be used in that advertisers’ campaigns. To learn more, see Advertisers.

[2](1, 2) Required if the audience is defined at the advertiser level.
integer Optional [2] Optional [2]
include

Read-only field that specifies included audiences. Each element of the parent array represents a unique audience group.

Use Search Audiences to identify relevant segments.

array N/A N/A
includeIds

Specifies included audiences.

Use Search Audiences to identify relevant segments.

This field is an array of arrays where each element of the parent array represents a unique audience group. Multiple audience groups are bound using AND logic wherein users that match the criteria of each group are included.

Within each group, the segments are bound using ANY logic wherein users that match any of the criteria are included.

array Required Optional
exclude

Read-only field that specifies excluded audiences.

Use Search Audiences to identify relevant segments.

array N/A N/A
excludeIds

Specifies excluded audiences.

Use Search Audiences to identify relevant segments.

array Optional Optional
clearAllExclude

Clears all excluded segments.

  • true: remove existing excluded segments.
  • false: do not remove existing excluded segments.
[3]If not specified when updating the audience, defaults to false.
boolean N/A Optional [3]

Segment Object

A composite audience object is comprised of multiple audiences (segments), which are identified by their segment IDs.

Using segment IDs, you may specify which audiences are included in or excluded from a composite audience.

Table 25 Segment Fields
Field Description Data Type
id Specifies the segment ID. integer
name Specifies the name of the segment. string
status

Specifies the current status of the audience. By default, ACTIVE.

Allowed values:

  • ACTIVE: the audience can be targeted.
  • INACTIVE: the audience cannot be targeted.
string
segmentType

Specifies the segment type of the audience.

Allowed values:

  • WEBSITE: Specifies a retargeting rule.
  • CONVERSIONRULE: Specifies a conversion rule audience. To learn more, see Conversion Rule Audience.
  • CUSTOM: Specifies a device ID audience. To learn more, see Device ID Audiences.
  • EMAIL: Specifies an email address audience. To learn more, see Email Address Audiences.
  • SRT: Specifies a search result audience. To learn more, see Search Keyword Audiences.
  • MRT: Specifies a mail domain audience. To learn more, see Mail Domain Audiences.
  • EVENTLEVEL: Specifies a mail event audience. To learn more, see Mail Event Audience.
  • FACT: Specifies a third-party data audience.
  • GEOTARGET: Specifies a POI location audience. To learn more, see POI Audiences.
  • INTEREST: Specifies a Yahoo Interest Categories audience.
  • MIC: Specifies a Mobile Interest Categories audience.
string
reachCount Specifies the unique number of consumers in the audience. integer
hierarchy Display the audience hierarchy as an array. array

Search Audiences

Search for audiences available to the specified account.

GET /traffic/audiences/composite/search?accountId={accountId}&query={query}&page={page}&limit={limit}

The response returns a list of audiences that match the specified query, which can be used to create a Composite audience.

Parameters

Table 26 Search Audience Parameters
Parameters Parameter Type Description Data Type Required
accountId query

Specifies the advertiser ID.

[4]Required in order to search for advertiser-level audiences.
integer Y [4]
query query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/search?accountId=1356341&query=Hilton%20Homewood&limit=2

Example Response

{
  "response": [
    {
      "name": "Nielsen Travel - Credit Card Data - Hotels and Motels - Hilton Homewood Suites_88571",
      "segmentType": "FACT",
      "reachCount": 1883281,
      "id": 20791579,
      "status": "ACTIVE",
      "hierarchy": [
        {
          "name": "Nielsen Travel - Credit Card Data - Hotels and Motels_36089"
        },
        {
          "name": "Nielsen Travel - Credit Card Data_169361"
        },
        {
          "name": "Nielsen Travel"
        },
        {
          "name": "Nielsen Segments"
        },
        {
          "name": "eXelate"
        },
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2019-04-03T21:34:39.849Z"
}

Read Composite Audience

Get data for a specific composite audience.

GET /traffic/audiences/composite/{id}?accountId={accountId}

Parameters

Table 27 Read Composite Audience Parameters
Parameters Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query

Specifies the advertiser ID.

[5]Required for advertiser-level audiences.
integer N [5]

Example Request URL (Seat-Level)

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/50436386

Example Response (Seat-Level)

{
  "response": {
    "id": 50436386,
    "name": "composite_test_seat",
    "status": "ACTIVE",
    "include": [
      [
        {
          "id": 50317502,
          "name": "FB_Converters_Created_League",
          "status": "ACTIVE",
          "segmentType": "CONVERSIONRULE",
          "reachCount": 32782
        },
        {
          "id": 20036700,
          "name": "(Del)APAC_HK_MRT_Macau Casino Resort",
          "status": "ACTIVE",
          "segmentType": "MRT",
          "reachCount": 258239
        }
      ],
      [
        {
          "hierarchy": [
            {
              "name": "Family"
            }
          ],
          "id": 20078721,
          "name": "Wedding",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 3583468
        }
      ]
    ],
    "exclude": [
      {
        "hierarchy": [
          {
            "name": "BoostBox"
          }
        ],
        "id": 50240870,
        "name": "Boostbox Special",
        "status": "ACTIVE",
        "segmentType": "FACT",
        "reachCount": 0
      },
      {
        "hierarchy": [
          {
            "name": "Yahoo Data"
          }
        ],
        "id": 20103062,
        "name": "Yahoo Mail",
        "status": "ACTIVE",
        "segmentType": "FACT",
        "reachCount": 1235090094
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:32:36Z"
}

Example Request URL (Advertiser-Level)

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/50410557?accountId=1356341

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50410557,
    "name": "test_composite",
    "accountId": 1356341,
    "status": "ACTIVE",
    "include": [
      [
        {
          "id": 50317502,
          "name": "FB_Converters_Created_League",
          "status": "ACTIVE",
          "segmentType": "CONVERSIONRULE",
          "reachCount": 32782
        },
        {
          "id": 20036700,
          "name": "(Del)APAC_HK_MRT_Macau Casino Resort",
          "status": "ACTIVE",
          "segmentType": "MRT",
          "reachCount": 258239
        }
      ],
      [
        {
          "hierarchy": [
            {
              "name": "Family"
            }
          ],
          "id": 20078721,
          "name": "Wedding",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 3583468
        }
      ]
    ],
    "exclude": [
      {
        "hierarchy": [
          {
            "name": "BoostBox"
          }
        ],
        "id": 50240870,
        "name": "Boostbox Special",
        "status": "ACTIVE",
        "segmentType": "FACT",
        "reachCount": 0
      },
      {
        "hierarchy": [
          {
            "name": "Yahoo Data"
          }
        ],
        "id": 20103062,
        "name": "Yahoo Mail",
        "status": "ACTIVE",
        "segmentType": "FACT",
        "reachCount": 1235090094
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:32:36Z"
}

Update Composite Audience

Update an existing composite audience.

PUT /traffic/audiences/composite/{id}

Partial updates are supported; values of supported fields which are not in the payload will remain unchanged.

Parameters

The audience id is specified in the endpoint path. All other fields are specified in the body of the application/json payload.

Example Request URL (Seat-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/50410557

Example Request Body (Seat-Level)

{
  "name":"updated_name",
  "includeIds": [
    [
      20103062
    ],
    [
      20078721
    ]
  ],
  "clearAllExclude":true
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50410557,
    "name": "updated_name",
    "status": "ACTIVE",
    "include": [
      [
        {
          "hierarchy": [
            {
              "name": "Yahoo Data"
            }
          ],
          "id": 20103062,
          "name": "Yahoo Mail",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 1235090094
        }
      ],
      [
        {
          "hierarchy": [
            {
              "name": "Family"
            }
          ],
          "id": 20078721,
          "name": "Wedding",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 3583468
        }
      ]
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:41:22Z"
}

Example Request URL (Advertiser-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/50410557?accountId=1356341

Example Request Body (Advertiser-Level)

{
  "accountId":1356341,
  "name":"updated_name",
  "includeIds": [
    [
      20103062
    ],
    [
      20078721
    ]
  ],
  "clearAllExclude":true
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50410557,
    "name": "updated_name",
    "accountId": 1356341,
    "status": "ACTIVE",
    "include": [
      [
        {
          "hierarchy": [
            {
              "name": "Yahoo Data"
            }
          ],
          "id": 20103062,
          "name": "Yahoo Mail",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 1235090094
        }
      ],
      [
        {
          "hierarchy": [
            {
              "name": "Family"
            }
          ],
          "id": 20078721,
          "name": "Wedding",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 3583468
        }
      ]
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:41:22Z"
}

Create Composite Audience

Create a new composite audience.

POST /traffic/audiences/composite

Parameters

All parameters are specified in the body of the application/json payload.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite

Example Request Body (Seat-Level)

{
  "name": "testcomposite8",
  "includeIds": [
    [
      20564215
    ],
    [
      50914330
    ]
  ],
  "excludeIds": [
    50914392
  ],
  "status": "INACTIVE"
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50914440,
    "name": "testcomposite8",
    "include": [
      [
        {
          "name": "test_clone",
          "segmentType": "WEBSITE",
          "reachCount": 16,
          "id": 20564215,
          "status": "ACTIVE"
        }
      ],
      [
        {
          "name": "test cr instrumentation 1554320019362_1Per30Days_RTG",
          "segmentType": "WEBSITE",
          "reachCount": 0,
          "id": 50914330,
          "status": "ACTIVE"
        }
      ]
    ],
    "exclude": [
      {
        "name": "test dot broker conversion rule 1554321908391_1Per30Days_RTG",
        "segmentType": "WEBSITE",
        "reachCount": 0,
        "id": 50914392,
        "status": "ACTIVE"
      }
    ],
    "status": "INACTIVE"
  },
  "errors": null,
  "timeStamp": "2019-04-03T21:05:48.347Z"
}

Example Request Body (Advertiser-Level)

{
  "accountId": 1356341,
  "name": "composite_test",
  "includeIds": [
    [
      20036700,
      50317502
    ],
    [
      20078721
    ]
  ],
  "excludeIds": [
    20103062,
    50240870
  ],
  "status": "ACTIVE"
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50410557,
    "name": "composite_test",
    "accountId": 1356341,
    "status": "ACTIVE",
    "include": [
      [
        {
          "id": 20036700,
          "name": "(Del)APAC_HK_MRT_Macau Casino Resort",
          "status": "ACTIVE",
          "segmentType": "MRT",
          "reachCount": 262103
        },
        {
          "id": 50317502,
          "name": "FB_Converters_Created_League",
          "status": "ACTIVE",
          "segmentType": "CONVERSIONRULE",
          "reachCount": 32669
        }
      ],
      [
        {
          "hierarchy": [
            {
              "name": "Family"
            }
          ],
          "id": 20078721,
          "name": "Wedding",
          "status": "ACTIVE",
          "segmentType": "FACT",
          "reachCount": 3928160
        }
      ]
    ],
    "exclude": [
      {
        "hierarchy": [
          {
            "name": "Yahoo Data"
          }
        ],
        "id": 20103062,
        "name": "Yahoo Mail",
        "status": "ACTIVE",
        "segmentType": "FACT",
        "reachCount": 1193947909
      },
      {
        "hierarchy": [
          {
            "name": "BoostBox"
          }
        ],
        "id": 50240870,
        "name": "Boostbox Special",
        "status": "ACTIVE",
        "segmentType": "FACT",
        "reachCount": 0
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T18:25:00Z"
}

Delete Composite Audience

The DSP Traffic API does not support deletion of composite audiences.