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 |
---|---|---|---|---|
|
Specifies the ad ID. |
|
N/A |
Required |
|
(Read-Only) Name of the ad. This value is inherited from the linked creative and should not be changed via this API. |
|
Required |
Optional |
|
Specifies the current status of the ad. Allowed values:
The following status type is read-only:
|
|
Required |
Optional |
|
Specifies the line ID. To learn more, refer to Lines. |
|
Required |
Optional |
|
Specifies the creative ID. To learn more, refer to Creatives. |
|
Required |
Optional |
|
(Read-Only) Ad media type.
|
|
N/A |
N/A |
|
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. |
|
Optional |
Optional |
|
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. |
|
Optional |
Optional |
|
(Read-Only) Last updated timestamp. |
|
N/A |
N/A |
|
Specifies the status of the ad. Valid input values are:
|
|
Optional |
Optional |
|
Specifies the list of “text” fields from the tag restrictions list of the ad. |
|
Optional |
Optional |
Ad Schedule Object¶
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the ad schedule ID. |
|
N/A |
Required |
|
Specifies the beginning of the schedule in |
|
Required |
Required |
|
Specifies the ending of the schedule in |
|
Required |
Required |
Ad Countdown Object¶
The countdown
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the ad countdown ID. |
|
N/A |
Required |
|
Specifies the countdown prefix to be used. To get supported values, refer to Premium Native Countdown Prefixes. |
|
Optional |
Optional |
|
Specifies the countdown end date and time in |
|
Required |
Required |
|
Specifies the timezone.
To learn more, refer to Timezones. Some example values: |
|
Required |
Required |
Read Ad¶
Get data for a specific ad.
GET /traffic/ads/{id}
Parameters¶
Parameters |
Parameter Type |
Description |
Data Type |
Required |
---|---|---|---|---|
|
path |
Specifies the ad ID. |
|
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 |
---|---|---|---|---|
|
query |
Specifies the line ID. |
|
Y |
|
query |
Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
|
N |
|
query |
Specifies the page number. |
|
N |
|
query |
Specifies the total number of items to return. Maximum allowed value is |
|
N |
|
query |
Specifies the column to sort by. |
|
N |
|
query |
Specifies the sort direction. Allowed values:
|
|
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.