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.