Composite Audience

Overview

A composite audience is built using a combination of advertiser data, Yahoo data, and third-party data. Audiences that use Yahoo data include unique signals that come from many different sources within Yahoo.

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 BrightRoll DSP.

Endpoint

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

Fields

The Composite audience payload contains the following fields:

Name Description Type Add Update
id ID of the audience segment. integer N/A Required
name Name of the segment. text Required Optional
status

Current status of the segment.

  • ACTIVE - (Default Value) Active.
  • INACTIVE - Inactive
text Optional Optional
accountId Advertiser/account ID associated with this segment. Refer to Advertisers. integer Required Required
include (Read-Only) Included audience segments. For field descriptions, see Search Audiences. Each element of the parent array represents a unique audience group. array of arrays N/A N/A
includeIds (Write-Only) Audience segment IDs to include. Use Search Audiences to find 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) Excluded audience segments. For field descriptions, see Search Audiences. array N/A N/A
excludeIds (Write-Only) Audience segment IDs to exclude. Use Search Audiences to find relevant segments. array Optional Optional
clearAllExclude

Note: This field is valid for PUT only.

  • true - Remove all existing exclude segments.
  • false - (Default Value) Do not remove any existing exclude segments.
boolean Optional Optional

Read Audience (Single)

To retrieve data for a specific Composite Audience, make a GET call with the parameters specified below.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/{id}?accountId={accountId}
Name Description Type Required?
id Audience / Segment ID integer Y
accountId Account or Advertiser ID integer Y

The response will be the Audience segment associated with the given ID.

Example Request

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

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

Update Audience

To update an existing Composite Audience, make a PUT call with a payload body and id parameter. The response will be the updated Audience.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

Example Request

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

Example Payload

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

Example Response

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

To create a new Composite Audience, make a POST call with a payload body. The response will be the newly created Audience.

Example Request

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

Example Payload

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

Example Response

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

Audience deletion is not supported by the API.

Search Audiences (Filtered)

To retrieve list of available audiences, make a GET call with the parameters specified below:

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/search?accountId={accountId}&query={query}&limit={limit}&page={page}
Name Description Type Required?
accountId Account or Advertiser ID. integer Y
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text N
limit Total number of items to return. Default is 50. integer N
page Page number. integer N

The response will be a list of matching segments which can be used to create a Composite audience.

Name Description
id Unique ID of the segment. This value can be used to create a new Composite audience.
name Segment name.
status

Current status of the segment.

  • ACTIVE
  • INACTIVE
segmentType

Segment (audience) type.

reachCount Number of unique user in this segment.
hierarchy Segment hierarchy.”

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