- 14 Minutes to read
Contextuals
- 14 Minutes to read
This article describes services for reading, adding, and updating contextuals.
Overview
A contextual is a business object that enables advertisers to target consumers by matching their interests and habits with a publisher’s content–that is, the context of the ad placement. The contextual specifies multiple parameters that identify both the consumer and the ad context.
Every contextual is defined by a taxonomy type that specifies the contextual categories that may define the contextual. A contextual category may specify a special area of interest (Arts and Entertainment, Automotive, Home and Garden), contexts to avoid i.e. brand safety (Alcohol, Drugs, Firearms), or the quality of the context (Home Page, Video Size, Ad Count).
Endpoint
/traffic/contextuals
Use the following HTTP methods:
Use the
GET
method to view an existing contextual.Use the
POST
method to create a new contextual.Use the
PUT
method to update an existing contextual.
Resources
Contextual
The contextuals
object contains the following fields:
Field | Description | Data Type | Create | Update |
---|---|---|---|---|
| Specifies the contextual ID. |
| N/A | Required |
| Specifies the name of the contextual. |
| Required | Optional |
| Specifies whether the contextual is a seat or advertiser-level contextual.
Note: To create seat-level contextuals, the Seat Ops role is required. |
| Required | Required |
| Specifies the taxonomy provider. Valid values include:
|
| Required | Optional |
| Specifies options to share a contextual with an advertiser(s). To learn more, refer to advertiserSharingSettings Object. |
| Optional | Optional |
| Specifies the advertiser ID. To learn more, refer to Advertisers. |
| Required if ownerType=ACCOUNT | Required if ownerType=ACCOUNT |
| Specifies the seat ID. Refer to Seats for further details. |
| Required if ownerType=SEAT | Required if ownerType=SEAT |
| Specifies options to target or block a seat-level contextual on all lines across channel(s) specified in a POST or PUT request. Refer to seatLevelTarget Object for further details. |
| Required if creating or updating a seat-level contextual | Required if creating or updating a seat-level contextual |
| Specifies an array of Category objects identified by To learn more, refer to Categories Array. |
| Required | Optional |
| A read-only field that shows the last updated timestamp. |
| N/A | N/A |
Categories Array
The categories
array contains the following fields:
Field | Description | Data Type |
---|---|---|
categoryId | Specifies the category ID. | integer |
Example Request Body
{
"categories": [
{
"categoryId": 2
},
{
"categoryId": 22
}
]
}
advertiserSharingSettings Object
The advertiserSharingSettings
object specifies options to share a contextual with an advertiser(s). The object contains the following fields:
Field | Description | Data Type | Create | Update |
---|---|---|---|---|
| Specifies the way in which a contextual is shared with a set of advertisers.
Note: If ALL is chosen, then specifying a list of advertisers is not required. |
| Required | Required |
| Specifies an array of advertisers to share a contextual with. |
| Required unless type=ALL | Required unless type=ALL |
| Specifies the advertiser ID. |
| Required | Required |
| Specifies the name of the advertiser. This field is optional, as the name of the advertiser will populate by default based on the ID. |
| Optional | Optional |
Example Request Body
{
"advertiserSharingSettings": {
"type": "INCLUDE",
"advertisers": [
{
"id": 2717418,
"name": "Canbaz Test Advertiser"
},
{
"id": 3227397,
"name": "Another Canbaz Test Advertiser"
}
]
}
}
seatLevelTarget Object
The seatLevelTarget object specifies options to target or block a seat-level contextual on all lines across channel(s) specified in a POST or PUT request. The object contains the following fields:
Field | Description | Data Type | Create | Update |
---|---|---|---|---|
| Specifies the seatLevelTarget ID. The ID appears in the responses of PUT or POST requests to verify that seat-level targeting was applied. |
| N/A. The ID is returned in the response. | Not required |
| Specifies an array of channel types that can be selected for targeting or blocking the contextual on all lines available for those channels in a seat.
|
| Required | Required |
| Specifies whether the contextual is targeted or blocked on lines across the selected channel types.
Note: Some contextual taxonomy types are not supported for targeting or blocking. |
| Required | Required |
Example Request Body
{
"seatLevelTarget": {
"channelSubTypes": [
"STANDARD_DISPLAY",
"NATIVE_DISPLAY"
],
"isExcluded": false
}
}
Read Contextual Categories
Get categories of taxonomy providers for the specified taxonomyType.
GET /traffic/contextuals/categories/{taxonomyType}
Parameters
The API takes a single parameter:
Parameter | Parameter Type | Description | Data Type | Required |
---|---|---|---|---|
| path | Specifies the taxonomy provider. Valid values include:
|
| Y |
Example Request URL
GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/categories/PUBLISHER_DECLARED
Example Response (Partial)
{
"response": [
{
"id": 1,
"description": "Arts & Entertainment",
"parentCategoryId": 0,
"level": 1,
"children": [
{
"id": 101,
"description": "Books & Literature",
"parentCategoryId": 1,
"level": 2
},
{
"id": 102,
"description": "Celebrity Fan/Gossip",
"parentCategoryId": 1,
"level": 2
}
]
},
{
"id": 2,
"description": "Automotive",
"parentCategoryId": 0,
"level": 1,
"children": [
{
"id": 201,
"description": "Auto Parts",
"parentCategoryId": 2,
"level": 2
}
]
}
],
"errors": null,
"timeStamp": "2017-07-17T18:00:12Z"
}
Read Contextual
Read a specific contextual.
GET /traffic/contextuals/{id}
Parameters
Parameter | Parameter Type | Description | Data Type | Required |
---|---|---|---|---|
| path | Specifies the contextual ID. |
| Y |
Example Request URL
GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/45067
Example Response
{
"response": {
"taxonomyType": "PUBLISHER_DECLARED",
"id": 45067,
"accountId": 1356341,
"name": "contextual_update_test",
"updatedAt": "2017-09-22T04:25:00Z",
"categories": [
{
"id": 135759,
"categoryId": 2
},
{
"id": 135760,
"categoryId": 22
}
]
},
"errors": null,
"timeStamp": "2017-09-22T04:37:53Z"
}
Read Seat-Level Contextuals
Get a list of all seat-level contextuals that are being targeted or blocked on lines in a seat using the following GET method statement.
GET /traffic/contextuals?seatId={seatId}
A filtered list of seat-level contextuals can also be returned if using any of the following additional query parameters in the GET method statement.
GET /traffic/contextuals?seatId={seatId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
Parameters
To get the full list of seat contextuals, specify
the seatId query parameter in the URL path. All other fields needed are specified in the request body.
To return a filtered list of seat contextuals, use any of the following query parameters in the URL path.
Parameter | Description | Data Type | Required |
---|---|---|---|
| Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
| N |
| Specifies the page number. |
| N |
| Specifies the total number of items to return. Maximum allowed value is |
| N |
| Specifies the column to sort by. |
| N |
| Specifies the sort direction. Allowed values:
|
| N |
Example Request URL
GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals?seatId=123
Example Response
{
"response": [
{
"id": 123456,
"seatId": 123,
"ownerType": "SEAT",
"name": "Sample_traffic_test",
"updatedAt": "2022-08-12T09:40:01Z",
"categories": [
{
"id": 3456,
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"seatLevelTarget": {
"id": 200,
"channelSubTypes": [
"STANDARD_DISPLAY",
"NATIVE_DISPLAY"
],
"isExcluded": false
}
},
"errors": null,
"timeStamp": "2022-08-12T09:40:01.336Z"
{
"id": 123746,
"seatId": 123,
"ownerType": "SEAT",
"name": "Sample_traffic_test_2",
"updatedAt": "2022-08-12T09:40:01Z",
"categories": [
{
"id": 3456,
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"seatLevelTarget": {
"id": 200,
"channelSubTypes": [
"STANDARD_DISPLAY",
"NATIVE_DISPLAY",
"STANDARD_VIDEO",
"NATIVE_VIDEO"
],
"isExcluded": false
}
}
"errors": null,
"timeStamp": "2022-08-12T09:40:01.336Z"
]
}
Read Advertiser Contextuals
Read a filtered list of advertiser-level contextuals.
GET /traffic/contextuals?accountId={accountId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
All of the accepted parameters are query parameters.
Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
| Specifies the advertiser ID. |
| Y |
| Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
| N |
| Specifies the page number. |
| N |
| Specifies the total number of items to return. Maximum allowed value is |
| N |
| Specifies the column to sort by. |
| N |
| Specifies the sort direction. Allowed values:
|
| N |
Example Request URL
GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals?accountId=1356341&query=test&page=1&limit=2
Example Response
{
"response": [
{
"taxonomyType": "PUBLISHER_DECLARED",
"id": 45067,
"accountId": 1356341,
"name": "contextual_update_test",
"updatedAt": "2017-09-22T04:25:00Z",
"categories": [
{
"id": 135759,
"categoryId": 2
},
{
"id": 135760,
"categoryId": 22
}
]
},
{
"taxonomyType": "DOUBLE_VERIFY",
"id": 45068,
"accountId": 1356341,
"name": "dv_test_1",
"updatedAt": "2017-09-22T04:29:24Z",
"categories": [
{
"id": 135762,
"categoryId": 50260081
}
]
}
],
"errors": null,
"timeStamp": "2017-09-22T04:33:26Z"
}
Create an Advertiser Contextual
Create a new advertiser-level contextual.
POST /traffic/contextuals
Parameters
All fields are specified in the request body.
Example Request URL
POST https://dspapi.admanagerplus.yahoo.com/traffic/contextuals
Example Request Body
The following request shows an example of creating an account-level contextual.
{
"ownerType": "ACCOUNT",
"accountId": 1356341,
"name": "iab_test_1",
"taxonomyType": "PUBLISHER_DECLARED",
"categories": [
{
"categoryId": 2
},
{
"categoryId": 22
}
]
}
Example Response
{
"response": {
"id": 45067,
"ownerType": "ACCOUNT",
"accountId": 1356341,
"name": "iab_test_1",
"updatedAt": "2017-09-22T04:12:01Z",
"categories": [
{
"id": 135757,
"categoryId": 2
},
{
"id": 135758,
"categoryId": 22
}
]
"taxonomyType": "PUBLISHER_DECLARED",
},
"errors": null,
"timeStamp": "2017-09-22T04:12:00Z"
}
Create a Seat Contextual
Create a seat-level contextual to target or block on all lines across the channel(s) specified in the request body.
Important
Only brand safety or custom contextuals can be created at the seat level.
POST /traffic/contextuals
Parameters
All fields needed are specified in the request body.
Example Request URL
https://dspapi.admanagerplus.yahoo.com/traffic/contextuals
Example Request Body
The following request shows an example of creating a seat-level contextual and targeting it on all standard display and 3rd party native display lines.
{
"seatId": 123,
"ownerType": "SEAT",
"name": "Sample_traffic_test",
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"categories": [
{
"categoryId": 50541444
}
],
"seatLevelTarget": {
"channelSubTypes": [
"STANDARD_DISPLAY",
"NATIVE_DISPLAY"
],
"isExcluded": false
}
}
Example Response
{
"response": {
"id": 123456,
"seatId": 123,
"ownerType": "SEAT",
"name": "Sample_traffic_test",
"updatedAt": "2022-08-12T09:40:01Z",
"categories": [
{
"id": 3456,
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"seatLevelTarget": {
"id": 200,
"channelSubTypes": [
"STANDARD_DISPLAY",
"NATIVE_DISPLAY"
],
"isExcluded": false
}
},
"errors": null,
"timeStamp": "2022-08-12T09:40:01.336Z"
}
Create and Share an Advertiser Contextual
Create an advertiser-level contextual and share it with any advertiser(s) specified in the request body.
POST /traffic/contextuals
Parameters
All fields needed are specified in the request body.
Example Request URL
https://dspapi.admanagerplus.yahoo.com/traffic/contextuals
Example Request Body
The following request shows an example of creating a contextual and sharing it with only two advertisers.
{
"ownerType": "ACCOUNT",
"accountId": 12075,
"name": "Traffic POST Test 2",
"categories": [
{
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"advertiserSharingSettings": {
"type": "INCLUDE",
"advertisers": [
{
"id": 2717418,
"name": "Canbaz Test Advertiser"
},
{
"id": 3227397,
"name": "Another Canbaz Test Advertiser"
}
]
}
}
Example Response
{
"response": {
"id": 366490,
"ownerType": "ACCOUNT",
"accountId": 12075,
"name": "Traffic POST Test 2",
"updatedAt": "2022-07-18T21:12:17Z",
"categories": [
{
"id": 818038,
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"advertiserSharingSettings": {
"type": "INCLUDE",
"advertisers": [
{
"id": 2717418,
"name": "Canbaz Test Advertiser"
},
{
"id": 3227397,
"name": "Another Canbaz Test Advertiser"
}
]
}
},
"errors": null,
"timeStamp": "2022-07-18T21:12:26.196Z"
}
Update Contextual
Update an existing contextual.
PUT /traffic/contextuals/{id}
Partial updates are supported; values of supported fields that are not in the payload remain unchanged.
Parameters
The Contextual id
is specified in the url path. All other fields are specified in the body of the application/json
payload.
Example Request URL
PUT https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/45067
Example Request Body
{
"accountId": 1356341,
"ownerType": "ACCOUNT",
"name": "contextual_update_test",
"taxonomyType": "PUBLISHER_DECLARED",
"categories": [
{
"categoryId": 14
}
]
}
Example Response
{
"response": {
"taxonomyType": "PUBLISHER_DECLARED",
"id": 45067,
"ownerType": "ACCOUNT",
"accountId": 1356341,
"name": "contextual_update_test",
"updatedAt": "2017-09-22T04:25:00Z",
"categories": [
{
"id": 135759,
"categoryId": 2
},
{
"id": 135760,
"categoryId": 22
},
{
"id": 135761,
"categoryId": 14
}
]
},
"errors": null,
"timeStamp": "2017-09-22T04:24:59Z"
}
Update a Seat Contextual
Use the PUT method to:
Change a seat-level contextual to targeted or blocked on lines across additional channels, but only if the contextual is supported for targeting or blocking.
Include additional channel types to target or block the contextual on all lines for those channels.
Add more contextual categories to the contextual.
PUT /traffic/contextuals/{id}
Parameters
Specify the contextual id path parameter in the request URL. All other fields are specified in the request body.
Example Request URL
PUT https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/123456
Example Request Body
The following request shows an example of updating a seat-level contextual to add two new contextual categories to the contextual for targeting on standard display lines.
{
"id": 123456,
"seatId": 123,
"ownerType": "SEAT",
"name": "Sample_traffic_test",
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"categories": [
{
"categoryId": 50541444
},
{
"categoryId": 50541453
},
],
"seatLevelTarget": {
"channelSubTypes": [
"STANDARD_DISPLAY"
],
"isExcluded": false
}
}
Example Response
{
"response": {
"id": 123456,
"seatId": 123,
"ownerType": "SEAT",
"name": "Sample_traffic_test",
"updatedAt": "2022-08-12T09:40:01Z",
"categories": [
{
"id": 3456,
"categoryId": 50541444
},
{
"id": 3457,
"categoryId": 50541453
},
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"seatLevelTarget": {
"id": 200,
"channelSubTypes": [
"STANDARD_DISPLAY"
],
"isExcluded": false
}
},
"errors": null,
"timeStamp": "2022-08-12T14:59:52.747Z"
}
Share a Contextual with Additional Advertisers
To share a contextual with additional advertisers, use the following PUT method statement.
PUT /traffic/contextuals/{id}
Parameters
The Contextual id path parameter is specified in the request URL. All other fields needed are specified in the request body.
Example Request URL
https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/366476
Example Request Body
The following request shows an example of adding one Advertiser to share the contextual with.
{
"id": 366476,
"ownerType": "ACCOUNT",
"accountId": 12075,
"name": "Traffic POST Test 1",
"updatedAt": "2022-07-14T00:12:57Z",
"categories": [
{
"id": 818009,
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"advertiserSharingSettings": {
"type": "INCLUDE",
"advertisers": [
{
"id": 2717418,
"name": "Canbaz Test Advertiser"
}
]
}
}
Example Response
{
"response": {
"id": 366476,
"accountId": 12075,
"name": "Traffic POST Test 1",
"updatedAt": "2022-07-14T00:12:57Z",
"categories": [
{
"id": 818009,
"categoryId": 50541444
}
],
"taxonomyType": "DOUBLE_VERIFY_BRAND_SAFETY",
"advertiserSharingSettings": {
"type": "INCLUDE",
"advertisers": [
{
"id": 2717418,
"name": "Canbaz Test Advertiser"
}
]
}
},
"errors": null,
"timeStamp": "2022-07-18T21:10:43.324Z"
}
Delete Contextual
The DSP Traffic API does not support deletion of contextuals.