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

integer

Required

Optional

creativeId

Specifies the creative ID.

To learn more, refer to 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, refer to 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

countdown

Specifies the Ad countdown timer information.

Only valid for ads created with Yahoo Native lines. If added, a dynamic countdown will be displayed on the ad based on its settings. While this attribute is optional in general, it is required if the creative has a {time} macro in the title or description. To learn more, refer to Ad Countdown Object.

object

Optional

Optional

updatedAt

(Read-Only) Last updated timestamp.

string

N/A

N/A

nativeAdStatus

Specifies the status of the ad. Valid input values are:

  • ACTIVE

  • PAUSED

  • ON_HOLD

  • ON_LIMITED

  • RESTRICTED

  • DELETED

  • REJECTED

string

Optional

Optional

nativeAdRestrictions

Specifies the list of “text” fields from the tag restrictions list of the ad.

array

Optional

Optional

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

Ad Countdown Object

The countdown object contains the following fields:

Field

Description

Data Type

Create

Update

id

Specifies the ad countdown ID.

integer

N/A

Required

countdownPrefixId

Specifies the countdown prefix to be used. To get supported values, refer to Premium Native Countdown Prefixes.

integer

Optional

Optional

endDate

Specifies the countdown end date and time in yyyy-MM-ddTHH:mm:ssZ format.

string

Required

Required

timezone

Specifies the timezone. To learn more, refer to Timezones. Some example values: America/New_York, Etc/GMT.

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/644808

Example Response

{
  "response": {
  "id": 644808,
  "name": "Creative DV Video Tags 1",
  "lineId": 1886417,
  "creativeId": 3125385,
  "updatedAt": "2021-12-07T15:15:30Z",
  "status": "ACTIVE",
  "nativeAdStatus": "ON_LIMITED",
  "nativeAdRestrictions": [
    "Antivirus or computer-cleaning software",
    “Apple competitors”
  ],
  "mediaType": "VIDEO",
  "schedules": []
  },
  "errors": null,
  "timeStamp": "2022-10-11T15:36:45.348Z"
}

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

Parameter 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 descending 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"
}

Create Native Ad

Create a new native ad with an optional countdown.

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",
  "mediaType": "NATIVE",
  "countdown": {
    "countdownPrefixId": 22,
    "endDate": "2020-09-25T23:59:56Z",
    "timezone": "America/New_York"
  }
}

Example Response

{
  "response": {
    "id": 506506,
    "name": "native-ad-standard",
    "lineId": 669814,
    "creativeId": 520828,
    "updatedAt": "2020-09-09T13:11:55Z",
    "status": "ACTIVE",
    "mediaType": "NATIVE",
    "schedules": [],
    "countdown": {
      "id": 1466,
      "countdownPrefixId": 22,
      "endDate": "2020-09-25T22:59:56Z",
      "timezone": "America/New_York"
    }
  },
  "errors": null,
  "timeStamp": "2020-09-09T13:12:00.841Z"
}

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.