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.

Endpoints

You can read, update, and create composite audiences via the composite resource.

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

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?

The request returns an array of audience objects that provide audience details. To learn more, see Search Audiences.

Resources

The composite resource defines a composite audience. The composite resource contains the following fields:

Table 25 Composite Audience Resource
Field Description Type Add 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. By default, ACTIVE. Options include:

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string Optional Optional
accountId

Specifies the advertiser ID.

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

[1](1, 2) Required if the composite audience is defined at the advertiser level.
string Optional [1] Optional [1]
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 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 specifies excluded audiences.

Use Search Audiences to identify relevant segments.

array Optional Optional
clearAllExclude

Clears all exclude segments. By default, false.

  • If true, remote existing exclude segments.
  • If false, do not remote exclude segments.
boolean N/A Optional

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 audience are included in or excluded from a composite audience.

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. Options include:

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

Specifies the segment type of the audience. Options include:

  • 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

Read Composite Audiences

Returns data for the specified composite audience.

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

The response returns the specified composite audience.

Parameters

Table 26 Read Seat-level Composite Audiences
Parameters Parameter Type Description Data Type Required
id path Specifies the composite audience ID. integer Y
accountId query

Specifies advertiser account ID.

[2]Required to search for advertiser-level audiences.
integer N [2]

Example Seat-Level Request

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

Example Seat-Level Response

{
  "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 Advertiser-Level Request

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

Example Advertiser-Level Response

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

Search Audiences

Retrieves audiences available to the specified account.

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

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

Parameters

All parameters are specified as a query appended to the endpoint.

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

Specifies the advertiser account ID.

[3]Required to search for advertiser-level audiences.
integer Y [3]
query query Specifies search terms. Use URL encoding conventions (i.e. a space should be replaced with a + or %20). string N
limit path Specifies the total number of items to return. By default, 50. string N
page path Specifies the page number. integer N

Example Request

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

Example Response

{
  "response": [
    {
      "hierarchy": [
        {
          "name": "Hotels and Motels"
        },
        {
          "name": "Credit Card Data"
        },
        {
          "name": "Nielsen Travel"
        },
        {
          "name": "Nielsen Segments"
        },
        {
          "name": "eXelate"
        },
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "id": 20791579,
      "name": "Hilton Homewood Suites",
      "status": "ACTIVE",
      "segmentType": "FACT",
      "reachCount": 38802592
    }
  ],
  "errors": null,
  "timeStamp": "2017-12-15T00:26:58Z"

Update Composite Audiences

Updates the composite audience specified.

PUT /traffic/audiences/composite/{id}

Parameters

Table 28 Update Composite Audience Parameters
Parameters Parameter Type Description Data Type Required
id path Specifies the composite audience ID. integer Y
name body Specifies the name of the composite audience. string N
status body

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

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string N
accountId body

Specifies the advertiser account ID associated with the composite audience. To learn more, see Advertisers.

[4]Required when updating an advertiser-level audience.
integer Y [4]
includeIds body

Specifies the segment IDs included in the composite audience as an array of arrays. The 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.

Use the Search Segments resource to identify segment IDs. To learn more, see Search Audiences.

array N
excludeIds body

Specifies the segment IDs excluded from the composite audience as an array of arrays. The 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.

Use the Search Segments resource to identify segment IDs. To learn more, see Search Audiences.

array N
clearAllExclude body

Clears excluded segment IDs. By default, false.

  • If true, clears existing excluded segment IDs.
  • If false, does not clear existing excluded segment IDs.
boolean N

Example Request

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

Example Payload (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"
}

Example Payload (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"
}

Create Composite Audiences

Creates a composite audience.

POST /traffic/audiences/composite

The response returns a new composite object.

Parameters

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

Table 29 Create Composite Audience Parameters
Parameters Parameter Type Description Data Type Required
name body Specifies the name of the composite audience. string N
status body

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

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string N
accountId body

Specifies the advertiser ID associated with the composite audience.

To learn more, see Advertisers.

integer N
includeIds body

Specifies an array of segment IDs that identify the segments that compose the composite audience.

included in the composite audience as an array of arrays. The 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.

Use the Search Segments resource to identify segment IDs. To learn more, see Search Audiences.

array Y
excludeIds body

Specifies the segment IDs excluded from the composite audience as an array of arrays. The 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.

Use the Search Segments resource to identify segment IDs. To learn more, see Search Audiences.

array N

Example Request

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

Example Payload (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"
}

Example Payload (Seat-Level)

{
   "name": "composite_test_seat",
   "includeIds": [
      [
         20078721
      ]
   ],
   "excludeIds": [
      20103062,
      50240870
   ],
   "status": "ACTIVE"
}

Example Response (Seat-Level)

{
 "response": {
     "id": 50436386,
     "name": "composite_test_seat",
     "status": "ACTIVE",
     "include": [
         [
             {
                 "hierarchy": [
                     {
                         "name": "Family"
                     }
                 ],
                 "id": 20078721,
                 "name": "Wedding",
                 "status": "ACTIVE",
                 "segmentType": "FACT",
                 "reachCount": 3132355
             }
         ]
     ],
     "exclude": [
         {
             "hierarchy": [
                 {
                     "name": "Yahoo Data"
                 }
             ],
             "id": 20103062,
             "name": "Yahoo Mail",
             "status": "ACTIVE",
             "segmentType": "FACT",
             "reachCount": 1174634780
         },
         {
             "hierarchy": [
                 {
                     "name": "BoostBox"
                 }
             ],
             "id": 50240870,
             "name": "Boostbox Special",
             "status": "ACTIVE",
             "segmentType": "FACT",
             "reachCount": 333151
         }
     ]
 },
 "errors": null,
 "timeStamp": "2018-02-02T21:53:07Z"
}

Delete Composite Audiences

The Oath Ad Platforms DSP does not support the deletion of composite audiences.