---
title: "Custom Audiences"
slug: "custom-audiences"
updated: 2026-04-21T13:53:51Z
published: 2026-04-21T13:53:51Z
canonical: "help.yahooinc.com/custom-audiences"
---

> ## 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.

# Custom Audiences

This endpoint supports the creation of `Custom Audiences` for the following audience types:

- Email Address
- Phone Number
- Device ID
- IP Address

## Hierarchy

Define a `Custom Audience` at the advertiser level.

## Endpoint

```plaintext
/traffic/audiences/customsegments
```

Use the following HTTP methods:

- Use the `GET` method to read a custom audience.
- Use the `POST` method to create a custom audience.
- Use the `PUT` method to update a custom audience.

## Audience Types

The following audience types can *only* have these `subType` and `seedListType` combinations. *Note:* `isDeviceOnly` *cannot be set to* `TRUE` *for Email Address, Phone Number and IP Address audiences.*

| **Audience Type** | **subType** | **seedListType** | **isDeviceOnly supported?** |
| --- | --- | --- | --- |
| Email Address | `EMAIL` | `EMAIL` | No |
| Device ID | `CUSTOM` | - `IDFA`: Apple - `GPADVID`: Google | Yes |
| Phone Number | `PHONE_NUMBER` | `PHONE_NUMBER` | No |
| IP Address | `IPADDRESS` | `SHA256IP` | No |

## Resources

### Custom Audience Object

The `Custom Audience` audience object contains the following 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. Defaults to `ACTIVE` if a value is not specified. | `string` | Optional | Optional |
| `accountId` | Specifies the advertiser ID. An audience is tied to its [Advertiser](/dsp-api/docs/advertisers) and can only be used in that advertiser’s campaigns. | `integer` | Required | Required |
| `retentionDays` | Specifies the number of days custom audience data is retained. Allowed values: - `30` - `60` - `90` - `180` Defaults to `180` if a value is not selected. | `integer` | Optional | Optional |
| `subType` | Specifies the type of audience to be created. | `string` | Required | Optional |
| `seedList` | Specifies an array of data to be used as seed data for the audience. *Note:* - *The data should be hashed using the* [*SHA256*](https://en.wikipedia.org/wiki/SHA-2) *algorithm in all cases except for Device ID audiences.* - *All IPv6 addresses must be* [*normalized*](/dsp-api/docs/custom-audiences#normalize-ipv6-addresses) *before being hashed with the SHA-256 algorithm.* | `array` | Required | Optional |
| `seedListType` | Specifies the type of data included in the seedList. | `string` | Required | Optional |
| `seedListAction` | Specifies the operation which will be performed on the provided seedList. Allowed values: - `ADD`: insert the provided seedList entries. - `DELETE`: remove the provided seedList entries. Defaults to `ADD` if no value is specified. | `string` | Optional | Optional |
| `isDeviceOnly` | Enables or disables cross-device support. *Defaults to* `FALSE` *if a value is not specified.* If cross-device support is enabled, Yahoo DSP links cookie and mobile device identifiers deterministically at a person level and probabilistically at a household level. Disabling cross-device support turns off device linked cookies and restricts targeting to the uploaded/collected seed audience from a pixel. If cross-device targeting is disabled, the deterministic and probabilistic cross-device linkages are disabled for both creating and targeting a segment. Allowed values: - `TRUE`: disables cross device support. - `FALSE`: enables cross device support. *Note: This is only for use with Device ID audiences.* | `boolean` | Optional | Optional |
| `createdAt` | A read-only field that specifies when the audience was created. | `string` | N/A | N/A |

## Read an Audience

Read a specific `Custom Audience`.

```plaintext
GET traffic/audiences/customsegments/{id}?accountId={accountId}
```

### Parameters

| **Parameters** | **Parameter Type** | **Description** | **Data Type** | **Required** |
| --- | --- | --- | --- | --- |
| `id` | path | Specifies the audience ID. | `integer` | Y |
| `accountId` | query | Specifies the advertiser ID. | `integer` | Y |

### Sample Request URL

```plaintext
GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/customsegments/51525777?accountId=1406321
```

### Sample Response

```json
{
  "response": {
    "status": "ACTIVE",
    "id": 51525777,
    "name": "dev_id_56",
    "accountId": 1406321,
    "createdAt": "2020-02-01",
    "isDeviceOnly": false
  },
  "errors": null,
  "timeStamp": "2020-02-01T05:12:41.049Z"
}
```

## Create an Audience

Create a new `Custom Audience`.

```plaintext
POST /traffic/audiences/customsegments
```

### Parameters

Specify all fields in the body of the `application/json` payload.

### Sample Request URL

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

### Sample Request Body

```json
{
  "accountId": 2757689,
  "name": "Traffic Create IP Custom Audience",
  "seedListType": "SHA256IP",
  "seedListAction": "ADD",
  "seedList": [
      "4cda9cd051e28cce2c10baa075b16fce29dc20014d443004ea9fac1b532c5453",
      "edd1f211054d7c1f7d5cc4baceedb4d9b5231d65aa82ea0892f8ab821e6d2006",
      "d230a1f9533d2218bcdce1c67a1b89c057c0c7adb2e2b53d4e2f8ac296aa9530",
      "e2ac40fc7e5fc9571c0952491784f948bc6a98549db1a33a6abdda993ff1e0d9"
  ],
  "status": "ACTIVE"
}
```

### Sample Response

```json
{
   "response": {
     "status": "ACTIVE",
     "id": 53095732,
     "name": "Traffic Create IP Custom Audience",
     "accountId": 2757689,
     "retentionDays": 180,
     "createdAt": "2021-05-14"
   },
   "errors": null,
   "timeStamp": "2021-05-14T10:03:54.060Z"
}
```

## Update an Audience

Update an existing `Custom Audience`.

```plaintext
PUT /traffic/audiences/customsegments/{id}
```

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

### Parameters

Specify the audience `id` in the endpoint path. Specify all other fields in the body of the `application/json` payload.

### Sample Request URL

```plaintext
PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/customsegments/53095732
```

### Sample Request Body

```json
{
  "accountId": 2757689,
  "name": "Traffic Create IP Custom Audience Updated",
  "status": "INACTIVE",
}
```

### Sample Response

```json
{
  "response": {
    "status": "INACTIVE",
    "id": 53095732,
    "name": "Traffic Create IP Custom Audience Updated",
    "accountId": 2757689,
    "retentionDays": 180,
    "createdAt": "2021-05-14"
  },
  "errors": null,
  "timeStamp": "2021-05-14T10:15:50.678Z"
}
```

## Delete Audience

The DSP does not support the deletion of a `Custom Audience`.

## Normalize IPv6 Addresses

Normalized IPv6 addresses are required for upload into the DSP API. IPv6 addresses must be normalized according to RFC 5952 normalization rules, so that the data can be 100% accurately matched after encryption. If IPv6 addresses are not normalized, a single IP address can be written in multiple valid formats (e.g., 2001:db8:0:0::1 and 2001:0db8::0001).

| Format | Description | Normalized Example |
| --- | --- | --- |
| **Full IPv6 Address** | 128-bit address, maximally compressed per RFC 5952 rules | 2001:db8::1 |

> [!WARNING]
> Important
> 
> - Submitting /64 prefixes or other CIDR blocks is not supported.
> - **IPv4-Mapped IPv6**: Do not submit addresses like ::ffff:192.168.1.1. Please hash the original IPv4 address instead.

## Normalization Rules (RFC 5952)

Normalize IPv6 addresses as follows.

1. **Suppress Leading Zeros**: Leading zeros in each 16-bit group must be removed.
  1. 2001:0db8 → 2001:db8
2. **Longest Zero Run (::):** Use :: to replace the longest consecutive sequence of all-zero groups.
  1. 2001:db8:0:0:0:0:0:1 → 2001:db8::1
3. **Tie-breaking:** If there are two zero runs of equal length, compress the **first (leftmost)** one.
  1. 2001:db8:0:0:1:0:0:1 → 2001:db8::1:0:0:1
4. **No Single Group Compression:** Do not use :: to replace a single 16-bit zero group. Use :0: instead.
  1. 2001:db8:0:1:0:0:0:1 → 2001:db8:0:1::1
5. **Lowercase:** All hexadecimal characters must be **lowercase**.
  1. 2001:DB8:AAAA::1 → 2001:db8:aaaa::1

## Verify Normalized IPv6 Addresses

The normalized IPv6 address must be verified using SHA256 hashing. The hash input must be the **UTF-8 encoded** normalized string with **no trailing newline**.

**To Verify the Normalized IPv6 Address:**

Run `echo -n "2001:db8::1" | sha256sum` in the terminal. The output must be `5afd19e...1ed536`. If it differs, the normalization or encoding is wrong.

> [!WARNING]
> Important
> 
> Trailing Newline
> 
> - Many echo commands add a \n which completely changes the hash. Always use echo -n.

## Examples of Normalized IPs

The following are examples of normalized IPv6 addresses with their hash results.

| Normalized Value | SHA256 Hash Result |
| --- | --- |
| 2001:db8::1 | 5afd19e856d1c18d17d600dfd2b5f534992333985e126c2a951047102c1ed536 |
| 2001:db8:aaaa:1::1 | a26075760baa14c6db85931695017ae4e20b56b01b017ceacbd5c6fe2f69eecc |
| fe80::202:b3ff:fe1e:8329 | a63b8244f25c80d6c736ddc532c28a17a448543b6b5e9dbff39d5c3187822c97 |
| 2001:db8:0:1::1 | a81588f63cc78f25925f96562007801a6b9bd628529c6812f6b968ff4ef03b81 |