Device ID Audiences

This article describes APIs for creating, and updating device ID audiences.

Overview

A device ID audience enables you to target custom, device-based audiences. Every device ID audience is based on a list of Apple iOS Identifier for Advertising (IDFA) IDs, or Google Play Advertising IDs (GPADVID) that you provide and use for line targeting.

Note

You can only build a device ID audience for one advertiser at a time, not for an entire seat.

Endpoint

Use this endpoint to read, update, or create beacons.

/traffic/audiences/device_id

The action taken depends on the HTTP method and the parameters specified.

  • Use the POST method to add new device ID audiences.
  • Use the PUT method to update existing device ID audiences.

The audience ID and advertiser account ID must be specified in the path of the endpoint to retrieve audience data. The API provides two endpoints from querying device ID audience data:

GET /traffic/audiences/device_id/{id}?accountId={accountId}
GET /traffic/audiences/device_id/{id}/history?accountId={accountId}
  • Use the GET method to read data for existing device ID audiences. You must specify.

Resources

The device ID audience payload contains the following fields:

Table 35 Device ID Audience Resource
Field Description Type Add 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. By default, ACTIVE. Options include:

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string Optional Optional
accountId

Specifies the advertiser ID.

If specified, the device ID audience is tied to a specific advertiser and can only be used in that advertiser’s campaigns. To learn more, see Advertisers.

string Required Required
seedList Specifies an array of device IDs. array Required Optional
seedListType

Specifies the type of devices that can be included. Options include:

  • IDFA: Apple (IDFA)
  • GPADVID: Google
array Required Optional
isDeviceOnly

Enable / Disable cross device support. Our Oath Identity Graph enhances cross-screen capabilities by linking all cookie and mobile device Identifiers deterministically at a person level and probabilistically at a household level. You can choose to turn off the cross device linked cookies and devices; in order to restrict the targeting to the seed audience, that you have uploaded, or collected via our pixel. This disables both deterministic and probabilistic cross device linkages during segment creation as well as targeting time. By default, false.

  • If true, disable cross device support.
  • If false, enable cross device support.
boolean N/A Optional
createdAt A read-only field that specifies the time the audience was created. string N/A N/A

Read Audiences by ID

Reads audience data for a specified device ID audience.

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

Parameters

The resource takes two parameters. Both are required.

Table 36 Read Audience by ID Parameters
Parameter Parmameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser’s account ID. integer Y

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/device_id/50346201?accountId=1356341

Example Response

The response returns the device ID audience associated with the specified ID.

{
  "response": {
    "id": 50346201,
    "name": "test_device_id",
    "status": "ACTIVE",
    "accountId": 1356341,
    "isDeviceOnly": false
  },
  "errors": null,
  "timeStamp": "2017-10-11T00:58:24Z"
}

Update Device ID Audiences

Updates the device ID audience associated with the specified ID.

PUT /traffic/audiences/device_id/{id}

Partial updates are supported; fields that are either not passed or passed as null will be ignored during update.

Parameters

Example Request

The audience ID must be specified in the endpoint path.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/device_id/50346201

All other parameters are specified in the body of the application/json payload:

{
  "name": "test_device_id-2",
  "accountId": 1356341
}

Example Response

The response returns the specified audience:

{
  "response": {
    "id": 50346201,
    "name": "test_device_id-2",
    "status": "ACTIVE",
    "accountId": 1356341,
    "isDeviceOnly": false
  },
  "errors": null,
  "timeStamp": "2017-10-11T06:23:53Z"
}

Create Device ID Audiences

Creates a new device ID audience.

POST /traffic/audiences/device_id

Parameters

All parameters are specified in the body of the application/json payload:

Example Request

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

All parameters are specified in the body of the application/json payload:

{
  "name": "test_device_id",
  "status": "ACTIVE",
  "accountId": 1356341,
  "seedList": [
    "34A668B2-03CF-11E5-8418-1697F925EC7B",
    "34a66c5e-03cf-11e5-8418-1697f925ec7b"
  ],
  "seedListType": "GPADVID"
}

Example Response

The response will be the newly created Audience.

{
  "response": {
    "id": 50346201,
    "name": "test_device_id",
    "status": "ACTIVE",
    "accountId": 1356341,
    "isDeviceOnly": false
  },
  "errors": null,
  "timeStamp": "2017-10-11T00:33:54Z"
}

Delete Device ID Audiences

The DSP Traffic API does not support deleting audiences.

Read Device ID Audience History

Returns the history and status of the specified device ID audience.

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

Parameters

The resource takes two parameters. Both are required.

Table 37 Read Audience by ID Parameters
Parameter Parmameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser’s account ID. integer Y

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/device_id/50346201/history?accountId=1356341

Example Response

{
  "response": [
    {
      "id": "AUDAP_PreScored_20171012T0311348424657",
      "status": "Completed",
      "failPercentage": 0,
      "type": "IDFA",
      "createdDate": "2017-10-12T03:11:35",
      "errorMessage": "",
      "failedRecords": [],
      "totalIds": 2,
      "duplicated": 0,
      "totalFailed": 0
    },
    {
      "id": "AUDAP_PreScored_20171012T0307180667358",
      "status": "Completed",
      "failPercentage": 0,
      "type": "GPADVID",
      "createdDate": "2017-10-12T03:07:18",
      "errorMessage": "",
      "failedRecords": [],
      "totalIds": 2,
      "duplicated": 0,
      "totalFailed": 0
    }
  ],
  "errors": null,
  "timeStamp": "2017-10-12T03:11:48Z"
}