Composite Audiences

This article describes resources and services you can use to view, create, and update composite audiences.

Overview

You can build and target custom composite audiences that are based on a combination of first-party data, third-party data, and Verizon Media 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 Verizon Media DSP.

Hierarchy

You can define a Composite audience at the seat level or the advertiser level.

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

Endpoint

/traffic/audiences/composite

Use the following HTTP methods:

  • Use the GET method to view a composite audience.
  • Use the POST method to create a new composite audience.
  • Use the PUT method to update an existing composite audience.

Search Audiences to get a list of available segments that you can use to build a composite audience.

/traffic/audiences/composite/search

Resources

Composite Audience Object

The Composite audience object contains the following fields:

Field Description Data Type Create Update
id Specifies the audience ID. integer N/A Required
name Specifies the audience name. string Required Optional
status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: You can target the audience.
  • INACTIVE: You cannot target the audience.

Defaults to ACTIVE if you don’t specify a value.

string Optional Optional
accountId

Specifies the advertiser ID.

If you specify an advertiser ID, you can only use the audience for that advertiser’s campaigns. To learn more, see Advertisers.

integer Required for advertiser-level audiences, do not use for seat-level audiences. Required for advertiser-level audiences, do not use for seat-level audiences.
include

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

Search Audiences to get a list of available segments.

array (an array of arrays) N/A N/A
includeIds

Specifies included audiences.

Each element of the parent array is a unique audience group. Audience groups are bound by AND logic; users that match the criteria of each group are included.

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

Search Audiences to get a list of available segments.

array Required Optional
exclude

Read-only field that specifies excluded audiences.

Search Audiences to get a list of available segments.

array N/A N/A
excludeIds

Specifies excluded audiences.

Search Audiences to get a list of available segments.

array Optional Optional
clearAllExclude

Clears all excluded segments.

  • true: remove existing excluded segments.
  • false: do not remove existing excluded segments.

Defaults to false if you don’t specify a value.

boolean N/A Optional

Segment Object

A composite audience is made up of multiple segments, each with its own segment ID.

Use segment IDs to include audiences in (or exclude audiences from) a composite audience.

Field Description Data Type
id Specifies the segment ID. integer
name Specifies segment name. string
status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: you can target the audience.
  • INACTIVE: you cannot target the audience.
string
segmentType

Specifies the segment type of the audience.

Allowed values:

string
reachCount Specifies the unique number of users in the audience. integer
hierarchy Displays 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.

Parameters

Parameters Parameter Type Description Data Type Required/Optional
accountId query

Specifies the advertiser ID.

Required to search for advertiser-level audiences.

integer Required
query query

Specifies the search term.

Use URL encoding conventions (i.e. replace spaces with a + or %20).

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

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

View Composite Audience

View a specific composite audience.

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

Parameters

Parameters Parameter Type Description Data Type Required/Optional
id path Specifies the audience ID. integer Required
accountId query Specifies the advertiser ID. integer Required for advertiser-level audiences. Do not use for seat-level audiences.

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

Create Composite Audience

Create a new composite audience.

POST /traffic/audiences/composite

Parameters

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

Update Composite Audience

Update an existing composite audience.

PUT /traffic/audiences/composite/{id}

Partial updates are supported; values of supported fields that are not in the payload 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"
}

Delete Composite Audience

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