Contextuals
  • 14 Minutes to read

    Contextuals


      Article summary

      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:

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

      • PUBLISHER_DECLARED - Specifies a Publisher Declared contextual.

      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, refer to Advertisers.

      integer

      Required if ownerType=ACCOUNT

      Required if ownerType=ACCOUNT

      seatId

      Specifies the seat ID. Refer to Seats for further details.

      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, refer to 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:

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

      • PUBLISHER_DECLARED - Specifies a Publisher Declared contextual.

      string

      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

      id

      path

      Specifies the contextual ID.

      integer

      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

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

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


      Was this article helpful?

      What's Next