---
title: "Ads"
slug: "ads"
updated: 2024-09-22T22:25:33Z
published: 2024-09-22T22:25:33Z
canonical: "help.yahooinc.com/ads"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```plaintext
/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](https://developer.yahooinc.com/dsp/api/docs/traffic/lines.html). | `integer` | Required | Optional |
| `creativeId` | Specifies the creative ID. To learn more, refer to [Creatives](https://developer.yahooinc.com/dsp/api/docs/traffic/creatives.html). | `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](https://developer.yahooinc.com/dsp/api/docs/traffic/ads.html#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](https://developer.yahooinc.com/dsp/api/docs/traffic/ads.html#ad-countdown-object). | `object` | 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 |

## 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](https://help.yahooinc.com/dsp-api/docs/data-dictionary#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](https://help.yahooinc.com/dsp-api/docs/data-dictionary#timezones). Some example values: `America/New_York`, `Etc/GMT`. | `string` | Required | Required |

## Read Ad

Get data for a specific ad.

```plaintext
GET /traffic/ads/{id}
```

### Parameters

| **Parameters** | **Parameter Type** | **Description** | **Data Type** | **Required** |
| --- | --- | --- | --- | --- |
| `id` | path | Specifies the ad ID. | `integer` | Y |

### Example Request URL

```plaintext
GET https://dspapi.admanagerplus.yahoo.com/traffic/ads/644808
```

### Example Response

```json
{
  "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.

```plaintext
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

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

### Example Response

```plaintext
{
  "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.

```plaintext
POST /traffic/ads
```

### Parameters

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

Example Request URL

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

### Example Request Body

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

### Example Response

```plaintext
{
  "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.

```plaintext
POST /traffic/ads
```

### Parameters

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

### Example Request URL

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

### Example Request Body

```plaintext
{
  "lineId": 361734,
  "creativeId": 358605,
  "status": "ACTIVE",
  "mediaType": "NATIVE",
  "countdown": {
    "countdownPrefixId": 22,
    "endDate": "2020-09-25T23:59:56Z",
    "timezone": "America/New_York"
  }
}
```

### Example Response

```plaintext
{
  "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.

```plaintext
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

```plaintext
PUT https://dspapi.admanagerplus.yahoo.com/traffic/ads/152630
```

### Example Request Body

```plaintext
{
  "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

```plaintext
{
  "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.