Seats
  • 4 Minutes to read

    Seats


      Article summary

      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 Seat.

      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


      Was this article helpful?