Contextuals

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

id

Specifies the contextual ID.

integer

N/A

Required

name

Specifies the name of the contextual.

string

Required

Optional

ownerType

Specifies whether the contextual is a seat or advertiser-level contextual.

  • ACCOUNT - specifies that the contextual is an advertiser-level contextual.

  • SEAT - specifies that the contextual is a seat-level contextual.

Note: To create seat-level contextuals, the Seat Ops role is required.

string

Required

Required

taxonomyType

Specifies the taxonomy provider. Valid values include:

  • IAB - Specifies an IAB contextual.

  • DOUBLE_VERIFY_AUTHENTIC_BRAND_SAFETY - Specifies a Double Verify Authentic Brand Safety contextual. Requires an additional role.

  • DOUBLE_VERIFY - Specifies a Double Verify Brand Safety contextual. Requires an additional role.

  • IAS_BRAND_SAFETY - Specifies an IAS Brand Safety contextuals. Requires an additional role.

  • IAS_CONTEXTUAL - Specifies an IAS contextual.

  • IAS_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.

  • PEER39_BRAND_SAFETY - Specifies a Peer39 Brand Safety contextual. Requires an additional role.

  • PEER39_CONTEXTUAL - Specifies a Peer39 Content contextual. Requires an additional role.

  • PEER39_PAGE_LANGUAGE - Specifies a Peer39 Page Language contextual. Requires an additional role.

  • PEER39_PAGE_QUALITY - Specifies a Peer39 Page Quality contextual. Requires an additional role.

  • GRAPESHOT_BRAND_SAFETY - Specifies a Grapeshot Brand Safety contextual. Requires an additional role.

  • GRAPESHOT_CONTEXTUAL - Specifies a Grapeshot Contextual contextual. Requires an additional role.

  • GRAPESHOT_LANGUAGE - Specifies a Grapeshot Language contextual. Requires an additional role.

  • GRAPESHOT_CUSTOM - Specifies a Grapeshot Custom contextual. Requires an additional role.

string

Required

Optional

advertiserSharingSettings

Specifies options to share a contextual with an advertiser(s). To learn more, refer to advertiserSharingSettings Object.

object

Optional

Optional

accountId

Specifies the advertiser ID.

To learn more, see Advertisers.

integer

Required if ownerType=ACCOUNT

Required if ownerType=ACCOUNT

seatId

Specifies the seat ID. For more details, refer to Seats.

integer

Required if ownerType=SEAT

Required if ownerType=SEAT

seatLevelTarget

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.

object

Required if creating or updating a seat-level contextual

Required if creating or updating a seat-level contextual

categories

Specifies an array of Category objects identified by categoryId.

To learn more, see Categories Array.

array

Required

Optional

updatedAt

A read-only field that shows the last updated timestamp.

string

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

type

Specifies the way in which a contextual is shared with a set of advertisers.

  • INCLUDE - the contextual is shared with only the advertiser(s) specified in the advertisers array.

  • EXCLUDE - the contextual is shared with all advertiser(s) except for the ones specified in the advertisers array.

  • *ALL - the contextual is shared with all advertisers under a seat.

*Note: If ALL is chosen, then specifying a list of advertisers is not required.

string

Required

Required

advertisers

Specifies an array of advertisers to share a contextual with.

array

Required unless type=ALL

Required unless type=ALL

id

Specifies the advertiser ID.

integer

Required

Required

name

Specifies the name of the advertiser. This field is optional, as the name of the advertiser will populate by default based on the id.

string

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

id

Specifies the seatLevelTarget ID. The ID appears in the responses of PUT or POST requests to verify that seat-level targeting was applied.

integer

N/A. The ID is returned in the response

Not required

channelSubTypes

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.

  • “STANDARD_DISPLAY” - target or block the contextual on all standard display lines.

  • “STANDARD_VIDEO” - target or block the contextual on all standard video lines.

  • “NATIVE_DISPLAY” - target or block the contextual on all third party native display lines.

  • “NATIVE_VIDEO” - target or block the contextual on all third party native video lines.

  • “CTV” - target or block the contextual on all CTV lines.

array

Required

Required

isExcluded

Specifies whether the contextual is targeted or blocked on lines across the selected channel types.

  • false - specifies that the contextual will be targeted on all lines across the channels selected.

  • true - specifies that the contextual will be blocked on all lines across the channels selected.

Note: Some contextual taxonomy types are not supported for targeting or blocking.

boolean

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

taxonomyType

path

Specifies the taxonomy provider. Valid values include:

  • IAB - Specifies an IAB contextual.

  • DOUBLE_VERIFY_AUTHENTIC_BRAND_SAFETY - Specifies a Double Verify Authentic Brand Safety contextual. Requires an additional role.

  • DOUBLE_VERIFY - Specifies a Double Verify Brand Safety contextual. Requires an additional role.

  • IAS_BRAND_SAFETY - Specifies an IAS Brand Safety contextuals. Requires an additional role.

  • IAS_CONTEXTUAL - Specifies an IAS contextual.

  • IAS_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.

  • PEER39_BRAND_SAFETY - Specifies a Peer39 Brand Safety contextual. Requires an additional role.

  • PEER39_CONTEXTUAL - Specifies a Peer39 Content contextual. Requires an additional role.

  • PEER39_PAGE_LANGUAGE - Specifies a Peer39 Page Language contextual. Requires an additional role.

  • PEER39_PAGE_QUALITY - Specifies a Peer39 Page Quality contextual. Requires an additional role.

  • GRAPESHOT_BRAND_SAFETY - Specifies a Grapeshot Brand Safety contextual. Requires an additional role.

  • GRAPESHOT_CONTEXTUAL - Specifies a Grapeshot Contextual contextual. Requires an additional role.

  • GRAPESHOT_LANGUAGE - Specifies a Grapeshot Language contextual. Requires an additional role.

  • GRAPESHOT_CUSTOM - Specifies a Grapeshot Custom contextual. Requires an additional role.

string

Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/categories/IAB

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

id

path

Specifies the contextual ID.

integer

Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/45067

Example Response

{
  "response": {
    "taxonomyType": "IAB",
    "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

query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string

N

page

Specifies the page number.

integer

N

limit

Specifies the total number of items to return. Maximum allowed value is 100.

integer

N

sort

Specifies the column to sort by.

string

N

dir

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.

  • DESC: data is sorted in descending order.

string

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": "GRAPESHOT_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": "GRAPESHOT_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

accountId

Specifies the advertiser ID.

integer

Y

query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string

N

page

Specifies the page number.

integer

N

limit

Specifies the total number of items to return. Maximum allowed value is 100.

integer

N

sort

Specifies the column to sort by.

string

N

dir

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.

  • DESC: data is sorted in descending order.

string

N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals?accountId=1356341&query=test&page=1&limit=2

Example Response

{
  "response": [
    {
      "taxonomyType": "IAB",
      "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

{
  "ownerType": "ACCOUNT",
  "accountId": 1356341,
  "name": "iab_test_1",
  "taxonomyType": "IAB",
  "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": "IAB",
  },
  "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": "GRAPESHOT_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": "GRAPESHOT_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": "GRAPESHOT_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": "GRAPESHOT_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": "IAB",
  "categories": [
    {
      "categoryId": 14
    }
  ]
}

Example Response

{
  "response": {
    "taxonomyType": "IAB",
    "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": "GRAPESHOT_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": "GRAPESHOT_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": "GRAPESHOT_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": "GRAPESHOT_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.