Seats

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

Overview

In Oath Ad Platforms DSP, a seat is a licensed account that is held by an ad agency, trading desk, or direct advertiser that enables that organziation to participate in the real-time bidding marketplace.

Access to the Oath Ad Platforms DSP is controlled by means of a seat license, which enables a user account acting on behalf of an adverising agency or direct advertiser to access the Oath Ad Platforms DSP platform and manage the advertisers and campaigns belonging to that seat.

Individual users working on behalf of an advertising agency or direct advertiser can be assigned multiple seat licenses. A seat license enables a user to view, update, and create objects for the advertiser accounts that belong to that seat.

The Seats APIs enable three related operations:

  • Users may view the seats available to them. The Read Seats API enables you to view a list of the seat licenses available to you.
  • Users may switch between seats. The Switch Seats API enables you to switch between the seats available to you.
  • Clients may perform read, update, and write operations on advertiser data belonging to other seats. The Cross Seat Actions APIs enhance existing enpoints to facilitate cross-seat actions

Resources

Seat Object

The Read Seats and Switch Seats APIs return the seatLookups and currentSeat arrays, which contain information about the seats available to the user.

The seatLookups array displays an array of Seat objects. The Seat objects shows the name and id of the seats available to a user.

Table 120 Seat Object
Field Description Data Type
id Displays the seat ID. integer
name Displays the name of the seat. name

Current Seat Object

The Read Seats and Switch Seats APIs return the seatLookups and currentSeat arrays, which contain information about the seats available to the user.

The currentSeat object specifies the id, name, timezone, and currency the user’s current seat.

Table 121 Current Seat Object
Parameter Description Data Type
id Displays the seat ID. integer
name Displays the name of the seat. name
timezone Displays the seat’s time zone. string
currency Displays the seat’s currency. string

Read Seats

Returns an array of seats that are available to a user including the user’s current seat.

GET /traffic/seats

Use the seatId values returned to switch seats or to perform cross-seat actions on advertiser data belonging to other seats.

Parameters

The request takes no parameters.

Example Request

https://dspapi.admanagerplus.yahoo.com/traffic/seats

Example Response

The response returns seatLookups, an array of Seat objects, and the currentSeat object. To learn more, see Seat Object and Current Seat Object.

{
  "response": {
    "seatLookups": [
      {
        "id": 11,
        "name": "Core Digital Media"
      },
      {
        "id": 2,
        "name": "Test Seat"
      }
    ],
    "currentSeat": [
      {
        "id": 2,
        "name": "Test Seat",
        "timezone": "America/New_York",
        "currency": "USD"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2018-03-02T20:08:38Z"
}

Switch Seats

Switches the current user to the specified seat.

PUT /traffic/seats/switch

Parameters

The resource takes a single parameter that is specified in the body of the application/json payload.

Table 122 Swtich Seat Parameters
Parameter Parameter Type Description Data Type Required?
seatId body

Specifies of seat ID.

Use the read seats API to view available seat IDs. To learn more, see Read Seats.

integer Y

Example Request

The request specifies the seatId in the body of the request payload:

{
  "seatId": 11
}

Example Response

The response returns seatLookups, an array of Seat objects, and the currentSeat object. To learn more, see Seat Object and Current Seat Object.

{
  "response": {
    "seatLookups": [
      {
        "id": 11,
        "name": "Core Digital Media"
      },
      {
        "id": 2,
        "name": "Test Seat"
      }
    ],
    "currentSeat": [
      {
        "id": 11,
        "name": "Core Digital Media",
        "timezone": "America/Los_Angeles",
        "currency": "USD"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2018-03-06T19:04:58Z"
}

Cross Seat Actions

The Seat API enables you to operate on advertiser data belonging to another seat by specifying the seatId as a query parameter in the endpoint.

For example, the following three endpoints enable a user to read, update, and create a site list in the specified site list.

GET /traffic/sitelists/{id}?seatId={seatId}
PUT /traffic/sitelists/{id}?seatId={seatId}
POST /traffic/sitelists?seatId={seatId}

These endpoints are identical to the standard calls used to read, update, and create site lists, but for the addition of a seatId parameter that is appended to the endpoint.

A cross seat action temporarily switches a user to the required seat and then immediately switches that user back to the original seat.

Parameters

The only parameter required to perform an action across seats is the seatId of the targeted seat. Depending on the action performed, additional parameters may be required.

Table 123 Cross Seat Action Parameters
Parameter Parameter Type Description Data Type Required?
seatId query

Specifies the seat ID of the seat on which the action is performed.

Use the read seats API to view available seat IDs. To learn more, see Read Seats.

integer Y

Read Example

Read Request Example

The seatId is specified as a query parameter in the request.

GET /traffic/sitelists/69713?seatId=11

Read Response Example

{
  "response": {
    "status": "ACTIVE",
    "type": "SITE_LIST",
    "id": 69713,
    "name": "test555",
    "accountId": 1419175,
    "isShared": false,
    "updatedAt": "2017-11-10T23:13:58Z",
    "items": [
      {
        "id": 1995738,
        "itemName": "yahoo.com"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2018-03-03T01:11:12Z"
}

Create Example

Create Example Request

The seatId is specified as a query parameter in the request:

POST /traffic/sitelists?seatId=11

The parameters passed in the body of the application/json payload are identical to those specified the standard Create Site Lists request:

{
  "accountId": 1419175,
  "name": "test-site-list-1-x-seat",
  "status": "ACTIVE",
  "type": "SITE_LIST",
  "isShared": false,
  "items": [
    {
      "itemName": "http://google.com"
    }
  ]
}

Create Example Response

The response is identical to that of a standard Create Site Lists response:

{
  "response": {
    "status": "ACTIVE",
    "type": "SITE_LIST",
    "id": 75996,
    "name": "test-site-list-1-x-seat",
    "accountId": 1419175,
    "isShared": false,
    "updatedAt": "2018-03-03T01:27:37Z",
    "items": [
      {
        "id": 2004000,
        "itemName": "http://google.com"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2018-03-03T01:27:38Z"
}

Update Example

Update Example Request

The site list id is specified as a path parameter and the seatId are specified as a query parameter in the request:

PUT https://dspapi.admanagerplus.yahoo.com/traffic/sitelists/75996?seatId=11
{
  "accountId": 1419175,
  "status": "INACTIVE",
  "type": "SITE_LIST"
}

Update Example Response

The response is identical to that of a standard Update Site Lists response:

{
  "response": {
    "status": "INACTIVE",
    "type": "SITE_LIST",
    "id": 75996,
    "name": "test-site-list-1-x-seat",
    "accountId": 1419175,
    "isShared": false,
    "updatedAt": "2018-03-03T01:31:48Z",
    "items": [
      {
        "id": 2004001,
        "itemName": "http://google.com"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2018-03-03T01:31:49Z"
}

HTTP Status and Error Codes

Table 124 Status Codes
Status Code Description
422 Invalid account ID