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.

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 and can only be used in that advertiser’s campaigns.	`integer`	Required	Required
`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 algorithm in all cases except for Device ID audiences.	`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.

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

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

Parameter	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

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": 730,
     "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": 730,
    "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.