Seats

This article describes services for reading and updating seats.

Overview

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

Access to the Yahoo DSP is controlled by means of a seat license, which enables a user account acting on behalf of an advertising agency or direct advertiser to access the Yahoo 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 endpoints 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 contains information about the seats available to a user.

Field

Description

Data Type

id

Specifies the seat ID.

integer

name

Specifies the name of the seat.

string

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.

Parameter

Description

Data Type

id

Specifies the seat ID.

integer

name

Specifies the name of the seat.

string

timezone

Specifies the seat’s time zone.

string

currency

Specifies the seat’s currency.

string

Read Seats

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 URL

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

Example Response

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

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

integer

Y

Example Request URL

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

Example Request Body

{
  "seatId": 11
}

Example Response

{
  "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, performs the requested operation 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.

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, refer to 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 List 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 List 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-sitelist 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

Status Code

Description

422

Invalid account ID