- 4 Minutes to read
Seats
- 4 Minutes to read
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 |
---|---|---|
| Specifies the seat ID. |
|
| Specifies the name of the seat. |
|
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 |
---|---|---|
| Specifies the seat ID. |
|
| Specifies the name of the seat. |
|
| Specifies the seat’s time zone. |
|
| Specifies the seat’s currency. |
|
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 |
---|---|---|---|---|
| body | Specifies of seat ID. Use the read seats API to view available seat IDs. To learn more, refer to Read Seat. |
| 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 |
---|---|---|---|---|
| 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. |
| 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 |