Ads

This article describes services for reading, adding, and updating ads.

Overview

An ad is a creative that is linked to a line item and ready to serve on a web page.

Endpoint

/traffic/ads

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

  • Use the GET method to read an existing ad.
  • Use the POST method to create a new ad.
  • Use the PUT method to update an existing ad.

Resources

The ads resource is defined by the following following fields:

Field Description Data Type Create Update
id Specifies the ad ID. integer N/A Required
name (Read-Only) Name of the ad. This value is inherited from the linked creative and should not be changed via this API. string Required Optional
status

Specifies the current status of the ad.

Allowed values:

  • ACTIVE
  • INACTIVE

The following status type is read-only:

  • UNKNOWN
string Required Optional
lineId

Specifies the line ID.

To learn more, see Lines.

integer Required Optional
creativeId

Specifies the creative ID.

To learn more, see Creatives.

integer Required Optional
mediaType

(Read-Only) Ad media type.

  • DISPLAY
  • VIDEO
  • NATIVE
string N/A N/A
schedules

Specifies an array of Ad flight schedule objects.

Ad flight schedules are useful if you want to efficiently execute creative swaps. A creative swap is a precisely-timed replacement of one creative for another within the same line. To learn more, see Ad Schedule Object.

Setting up a flight schedule involves setting one or more start and end dates by the hour for each ad assigned to a line.

array Optional Optional
updatedAt (Read-Only) Last updated timestamp. string N/A N/A

Ad Schedule Object

Field Description Data Type Create Update
id Specifies the ad schedule ID. integer N/A Required
startDate Specifies the beginning of the schedule in yyyy-MM-ddTHH:mm:ssZ format. string Required Required
endDate Specifies the ending of the schedule in yyyy-MM-ddTHH:mm:ssZ format. string Required Required

Read Ad

Get data for a specific ad.

GET /traffic/ads/{id}

Parameters

Parameters Parameter Type Description Data Type Required
id path Specifies the ad ID. integer Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/ads/152630

Example Response

{
  "response": {
    "status": "ACTIVE",
    "mediaType": "DISPLAY",
    "id": 152630,
    "name": "ad-display-2x2",
    "lineId": 361734,
    "creativeId": 358605,
    "updatedAt": "2017-11-03T00:23:25Z",
    "schedules": [
      {
        "id": 338,
        "startDate": "2019-12-01T07:00:00Z",
        "endDate": "2020-01-05T06:59:59Z"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-11-03T00:23:25Z"
}

Read Ads

Get a filtered list of ads.

GET /traffic/ads?lineId={lineId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

Parameters

Parameter Paramerer Type Description Data Type Required
lineId query Specifies the line ID. integer Y
query query

Specifies the search term.

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

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the column to sort by. string N
dir query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.
  • DESC: data is sorted in decending order.
string N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/ads?lineId=361734&page=1&limit=20

Example Response

{
  "response": [
    {
      "status": "ACTIVE",
      "mediaType": "DISPLAY",
      "id": 148458,
      "name": "ad-display-2x2",
      "lineId": 361734,
      "creativeId": 358605,
      "updatedAt": "2017-11-02T21:42:20Z",
      "schedules": [
        {
          "id": 338,
          "startDate": "2019-12-01T07:00:00Z",
          "endDate": "2020-01-05T06:59:59Z"
        }
      ]
    },
    {
      "status": "ACTIVE",
      "mediaType": "DISPLAY",
      "id": 152630,
      "name": "ad-display-2x2",
      "lineId": 361734,
      "creativeId": 358605,
      "updatedAt": "2017-11-03T00:23:25Z",
      "schedules": [
        {
          "id": 339,
          "startDate": "2019-12-01T07:00:00Z",
          "endDate": "2019-12-05T06:59:59Z"
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2017-11-03T00:25:35Z"
}

Create Ad

Create a new ad.

POST /traffic/ads

Parameters

All fields are specified in the body of the application/json payload.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/ads

Example Request Body

{
  "lineId": 361734,
  "creativeId": 358605,
  "status": "ACTIVE",
  "schedules": [
    {
      "startDate": "2019-12-01T07:00:00Z",
      "endDate": "2019-12-05T06:59:59Z"
    }
  ]
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "mediaType": "DISPLAY",
    "id": 152630,
    "name": "ad-display-2x2",
    "lineId": 361734,
    "creativeId": 358605,
    "updatedAt": "2017-11-03T00:23:25Z",
    "schedules": [
      {
        "id": 340,
        "startDate": "2019-12-01T07:00:00Z",
        "endDate": "2019-12-05T06:59:59Z"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-11-03T00:23:25Z"
}

Update Ad

Update an existing ad.

PUT /traffic/ad/{id}

Partial updates are supported; values of supported fields that are not in the payload remain unchanged.

Parameters

The Ad 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/ads/152630

Example Request Body

{
  "status": "INACTIVE",
  "schedules": [
    {
      "id": 340,
      "startDate": "2020-01-01T07:00:00Z",
      "endDate": "2020-01-05T06:59:59Z"
    },
    {
      "startDate": "2020-02-01T00:00:00Z",
      "endDate": "2020-02-28T00:00:00Z"
    }
  ]
}

Example Response

{
  "response": {
    "status": "INACTIVE",
    "mediaType": "DISPLAY",
    "id": 152630,
    "name": "ad-display-2x2",
    "lineId": 361734,
    "creativeId": 358605,
    "updatedAt": "2017-11-03T00:43:55Z",
    "schedules": [
      {
        "id": 341,
        "startDate": "2020-02-01T00:00:00Z",
        "endDate": "2020-02-28T00:00:00Z"
      },
      {
        "id": 340,
        "startDate": "2020-01-01T07:00:00Z",
        "endDate": "2020-01-05T06:59:59Z"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-11-03T00:43:55Z"
}

Delete Ad

The DSP Traffic API does not support deletion of ads.