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

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

Resources

Custom Audience Object

The Custom Audience audience object contains the following fields:

Read an Audience

Read a specific Custom Audience.

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

Parameters

Sample Request URL

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

Sample Response

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

Read History

Get the history and status of a Custom Audience.

GET /traffic/traffic/audiences/customsegments/{id}/history?accountId={accountId}

Parameters

Sample Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/customsegments/53095732/history?accountId=2757689

Sample Response

{
  "response": [
    {
      "id": "AUDAP_Ipaddress_20210514T1144357342173",
      "status": "Active",
      "failPercentage": 0,
      "type": "SHA256IP",
      "createdDate": "2021-05-14T11:44:36"
    },
    {
      "id": "AUDAP_Ipaddress_20210514T1003346694717",
      "status": "Active",
      "failPercentage": 0,
      "type": "SHA256IP",
      "createdDate": "2021-05-14T10:03:35"
    }
  ],
  "errors": null,
  "timeStamp": "2021-05-14T11:46:31.034Z"
}

Create an Audience

Create a new Custom Audience.

POST /traffic/audiences/customsegments

Parameters

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

Sample Request URL

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

Sample Request Body

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

Sample Response

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

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

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

Sample Request Body

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

Sample Response

{
  "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).

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.

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.