---
title: "Composite"
slug: "composite"
updated: 2025-08-12T21:25:12Z
published: 2025-08-12T21:25:12Z
canonical: "help.yahooinc.com/composite"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Composite Audiences

Build and target custom *composite* audiences that are based on a combination of first-party data, third-party data and Yahoo data.

Use the following types of data to build a composite audience:

Custom Audience

An audience you build using advertiser-owned data such as retargeting rules, device IDs, anonymized email, phone number or IP addresses.

Yahoo Custom

An audience you build using Yahoo-owned data and your own search keywords, mail domains, purchase receipts, and Point of Interest (POI) locations.

Yahoo Standard

An audience you build using predefined segments that Yahoo configures and packages. Yahoo packaged audiences come from Yahoo’s Household & Lifestages and Interest categories.

Third Party

An audience you build using your third-party data. Most data management platforms (DMPs) are integrated with the Yahoo 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

```plaintext
/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](/dsp-api/docs/composite#search-audiences) to get a list of available segments that you can use to build a composite audience.

```plaintext
/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, refer to [Advertisers](/dsp-api/docs/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. [Include/Exclude Segment Object](/dsp-api/docs/composite#includeexclude-segment-object) to get a list of available fields. | `array` (an array of arrays) | N/A | N/A |
| `includeIds` | The ID of each included audience. Each element of the 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. Refer to [Search Audiences](/dsp-api/docs/composite#search-audiences) for available segments. | `array` | Required | Optional |
| `exclude` | Read-only field that specifies excluded audiences. [Include/Exclude Segment Object](/dsp-api/docs/composite#includeexclude-segment-object) to get a list of available fields. | `array` | N/A | N/A |
| `excludeIds` | The ID of each excluded audience. Refer to [Search Audiences](/dsp-api/docs/composite#search-audiences) for 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 |
| `fees` | Read-only field that specifies the audience fees. Refer to [Fees Object](/dsp-api/docs/composite#fees-object) for available fields. | `array` | N/A | N/A |
| `totalCount` | Read-only field that indicates the number of devices that comprise the segment. | `number` | N/A | N/A |
| `peopleCount` | Read-only field that indicates the number of unique people that can be reached by the segment. | `number` | N/A | N/A |

### Include/Exclude Segment Object

| **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: - `WEBSITE`: Specifies a retargeting rule. - `CONVERSIONRULE`: Specifies a [Conversion Rule Audiences.](/dsp-api/docs/conversion-rule) - `CUSTOM`: Specifies [Device ID Audiences](/dsp-api/docs/device-id). - `EMAIL`: Specifies [Email / Phone Number Audiences](/dsp-api/docs/email-phone-number). - `IPADDRESS`: Specifies [IP Address Audiences](/dsp-api/docs/ip-address). - `SRT`: Specifies [Search Keyword Audiences](/dsp-api/docs/search-keyword). - `MRT`: Specifies [Mail Domain Audiences](/dsp-api/docs/mail-domain). - `EVENTLEVEL`: Specifies a [Mail Event Audience](/dsp-api/docs/mail-event). - `FACT`: Specifies a third-party data audience. - `GEOTARGET`: Specifies [POI Audiences](/dsp-api/docs/point-of-interest). - `INTEREST`: Specifies a Yahoo Interest Categories audience. | `string` |
| `reachCount` | Read-only field that indicates the unique number of users in the audience. | `integer` |
| `hierarchy` | The audience hierarchy. | `array` |

### Fees Object

| **Field** | **Description** | **Data Type** |
| --- | --- | --- |
| `fee` | Fee value. | `number` |
| `currency` | Currency type. To learn more, refer to [Currency Types](https://help.yahooinc.com/dsp-api/docs/data-dictionary#currency-types). | `string` |
| `feeMediaType` | Media type. - `DISPLAY`: Specifies the display rate. - `VIDEO`: Specifies the video rate. | `string` |

## Search Audiences

Search for audiences available to the specified account.

```plaintext
GET /traffic/audiences/composite/search?accountId={accountId}&query={query}&country_codes={country_codes}&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 |
| `country_codes` | query | Specifies the country iso3 codes list (comma separated) used to filter out the segments based on their country availability. | `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 |

### Sample Request URL

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

### Sample Response

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

Read a specific composite audience.

```plaintext
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. |

### Sample Request URL (Seat-Level)

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

### Sample Response (Seat-Level)

```plaintext
{
  "response": {
    "id": 50436386,
    "name": "composite_test_seat",
    "status": "ACTIVE",
    "totalCount": 3529286,
    "peopleCount": 1193834,
    "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
      }
    ],
    "fees": [
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "DISPLAY"
      },
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "VIDEO"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:32:36Z"
}
```

### Sample Request URL (Advertiser-Level)

```plaintext
GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/{id}?accountId={accountId}
```

### Sample Response (Advertiser-Level)

```plaintext
{
  "response": {
    "id": 50410557,
    "name": "test_composite",
    "accountId": 1356341,
    "status": "ACTIVE",
    "totalCount": 3529286,
    "peopleCount": 1193834,
    "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
      }
    ],
    "fees": [
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "DISPLAY"
      },
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "VIDEO"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:32:36Z"
}
```

## Create Audience

Create a new composite audience.

```plaintext
POST /traffic/audiences/composite
```

### Parameters

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

### Sample Request URL

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

### Sample Request Body (Seat-Level)

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

### Sample Response (Seat-Level)

```plaintext
{
  "response": {
    "id": 50914440,
    "name": "testcomposite8",
    "status": "INACTIVE",
    "totalCount": 3529286,
    "peopleCount": 1193834,
    "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"
      }
    ],
    "fees": [
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "DISPLAY"
      },
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "VIDEO"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2019-04-03T21:05:48.347Z"
}
```

### Sample Request Body (Advertiser-Level)

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

### Sample Response (Advertiser-Level)

```plaintext
{
  "response": {
    "id": 50410557,
    "name": "composite_test",
    "accountId": 1356341,
    "status": "ACTIVE",
    "totalCount": 3529286,
    "peopleCount": 1193834,
    "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
      }
     ],
     "fees": [
       {
         "fee": 0.5,
         "currency": "USD",
         "feeMediaType": "DISPLAY"
       },
       {
         "fee": 0.5,
         "currency": "USD",
         "feeMediaType": "VIDEO"
       }
     ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T18:25:00Z"
}
```

## Update Audience

Update an existing composite audience.

```plaintext
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.

### Sample Request URL (Seat-Level)

```plaintext
PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/composite/50410558
```

### Sample Request Body (Seat-Level)

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

### Sample Response (Seat-Level)

```plaintext
{
  "response": {
    "id": 50410558,
    "name": "updated_name",
    "status": "ACTIVE",
    "status": "INACTIVE",
    "totalCount": 3529286,
    "peopleCount": 1193834,
    "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
        }
      ]
    ],
    "fees": [
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "DISPLAY"
      },
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "VIDEO"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:41:22Z"
}
```

### Sample Request URL (Advertiser-Level)

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

### Sample Request Body (Advertiser-Level)

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

### Sample Response (Advertiser-Level)

```plaintext
{
  "response": {
    "id": 50410557,
    "name": "updated_name",
    "accountId": 1356341,
    "status": "ACTIVE",
    "status": "INACTIVE",
    "totalCount": 3529286,
    "peopleCount": 1193834,
    "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
        }
      ]
    ],
    "fees": [
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "DISPLAY"
      },
      {
        "fee": 0.5,
        "currency": "USD",
        "feeMediaType": "VIDEO"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-12-21T04:41:22Z"
}
```

## Delete Audience

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