The DSP Reporting API enables a user to list, create, and update reports. The report query can contain several different filters and group by options within a time range and specific time zone. The response provides data similar to what a user sees in the Reporting view of the DSP for a given role.
View the following sections in this article:
- Authentication—You must first authenticate to use the DSP Reporting API.
- List reports—Retrieve a list of existing reports.
- Run a report—Run a single report any frequency with filters and different group by options. Note that this endpoint does not allow you to save the report.
- Create and save a report—Create, save, and schedule a report with filters and different group by options.
- Update and save a report—Update an existing report and save those changes.
- Get advertiser IDs - List existing advertisers to filter your reports with
- Buyer roles—Depending on your user role, you have the ability to apply filters, group by options, or aggregations to reports.
- Status codes—View the different status codes if you are experiencing issues while trying to authenticate.
Authentication
First, you must authenticate by using your login credentials (username and password) for the ad platform. Note that a cookie is set on your response so that you only need to authenticate once for a certain time period.
URL
POST https://staging.vistarmedia.com/session/
POST https://trafficking.vistarmedia.com/session/
Sample JSON request
{
"email": "myemail@vistarmedia.com",
"password": "mypassword"
}
List reports
Make a call to the API to retrieve a list of all reports.
URL
GET https://staging-trafficking.vistarmedia.com/reports/
GET https://trafficking.vistarmedia.com/reports/
Sample response
[
{
"groups": [],
"local_end": "2020-09-15T23:59:59",
"name": "Test Report",
"created": "2020-08-09T20:37:12+00:00",
"local_start": "2020-08-09T00:00:00",
"filters": {
"buy_type": [
"audience",
"deal"
]
},
"timezone": "America/New_York",
"last_updated": "2018-12-04T20:37:12+00:00",
"report_type": "exchange",
"id": "74l1vBJeSYaHIkXXXXXXXX"
},
{
"groups": [],
"local_end": "2020-10-14T23:59:59",
"name": "Test Report 2",
"created": "2018-12-04T20:37:12+00:00",
"local_start": "2020-08-08T00:00:00",
"filters": {
"buy_type": [
"audience",
"deal"
]
},
"timezone": "America/New_York",
"last_updated": "2018-12-04T20:37:12+00:00",
"report_type": "exchange",
"id": "74l1vBJeSYaHIkXXXXXXXX"
},
{
"last_updated": "2018-12-19T20:48:35+00:00",
"filters": {
"buy_type": [
"audience",
"deal"
]
},
"schedule": {
"start": "2018-11-20",
"frequency": {
"occurrence": "Daily"
},
"end": "2018-12-01",
"emails": [
"xxxxxxx@vistarmedia.com"
]
},
"local_end": "2020-11-26T23:59:59",
"created": "2020-09-01T23:38:19+00:00",
"local_start": "2020-09-01T00:00:00",
"groups": [
"advertiser"
],
"timezone": "America/New_York",
"report_type": "exchange",
"id": "74l1vBJeSYaHIkXXXXXXXX",
"name": "GroupbyAdvertiser"
}
...
]
Run a report
Make a call to the API to run a single report at any frequency. Note that this endpoint (/report
) enables you to create a report, without saving it. To save your report, use the Create and save a report endpoint (/reports
).
URL
POST https://staging-trafficking.vistarmedia.com/report
POST https://trafficking.vistarmedia.com/report
Body parameters
Name | Description | Type | Required | Notes | |||
filters | Depending on your role, you have access to certain filters. See the Buyer roles section in this article. | string | |||||
groups | Depending on your role, you have access to certain groups. See the Buyer roles section in this article. | string | Required | ||||
report_type |
This field must be one of the following:
|
string | Required | ||||
timezone |
For appropriate time zones, please see tz database time zones. For example: America/New_York |
string | Required | ||||
local_start |
The date and time in the specified timezone. For example: |
string | Required | ||||
local_end |
The date and time in the specified timezone. For example: |
string | Required | ||||
end* | Date and time using ISO 8601 format. | string | Deprecated |
*It is recommended to not use this field. You must use the |
|||
start* | Date and time using ISO 8601 format. | string | Deprecated |
*It is recommended to not use this field. You must use the |
Sample request
"filters": {
"us_state": [
"New York"
]
},
"groups": [
"month"
],
"local_start":"2019-03-22T00:00:00",
"local_end":"2019-03-28T23:59:59",
"timezone": "America/New_York",
"report_type": "exchange"
Create and save a report
Make a call to the API to create, save, and schedule a report. Note that if you want to create and save reports in bulk, use the bulk endpoint (/reports/
).
URL
POST https://staging-trafficking.vistarmedia.com/reports
POST https://trafficking.vistarmedia.com/reports
Body parameters
Name | Description | Type | Required | Notes | |||
name | Name of the report. | string | Required | ||||
filters | Depending on your role, you have access to certain filters. See the Buyer roles section in this article. | string | |||||
groups | Depending on your role, you have access to certain groups. See the Buyer roles section in this article. | string | Required | ||||
report_type |
This field must be one of the following:
|
string | Required | ||||
timezone | For appropriate time zones, please see tz database time zones. | string | Required | ||||
local_start |
The date and time in the specified timezone. For example: |
string | Required | ||||
local_end |
The date and time in the specified timezone. For example: |
string | Required | ||||
end* | Date and time using ISO 8601 format. | string | Deprecated |
*It is recommended to not use this field. You must use the |
|||
start* | Date and time using ISO 8601 format. | string | Deprecated |
*It is recommended to not use this field. You must use the |
|||
schedule | Schedule reports to be emailed to you and others on your team. | string | Optional | ||||
start | Date to begin the scheduled report. | string | Required* | *Required only if scheduling a report. | |||
frequency | Determine how often you want to receive an email of the report. | string | Required* | *Required only if scheduling a report. | |||
occurrence |
Enter one of the following:
To view the definitions for each option, see Build a report. |
string | Required* | *Required only if scheduling a report. | |||
value |
If you are scheduling a weekly report (in the
To view the definitions for each option, see Build a report. |
string | Required* | *Required only if scheduling a weekly report. | |||
end | Date to stop the scheduled report. | string | Optional | ||||
emails | Enter an additional email address to send the report to an additional user. | string | Required* | *Required only if scheduling a report. | |||
sanitized |
You have the option to share a report without the cost columns to additional users. This report only includes the Impressions and Revenue columns. Set one of the following options:
|
boolean | Required |
Sample request
{
"name":"Test Report 2",
"filters":{"advertiser":["52Ax4gk6SSe9F-XXXXXXXX"]},
"groups":["us_state"],
"report_type":"exchange",
"timezone":"America/New_York",
"local_end":"2020-10-01T23:59:59",
"local_start":"2019-10-01T00:00:00",
"schedule": {
"start": "2019-10-22",
"frequency": {
"occurrence": "Weekly",
"value": "MON"
},
"end": "2019-11-01",
"emails": [
"XXXXXXXX@vistarmedia.com"
],
"sanitized": false
}
}
Sample response
{
"last_updated": "2019-10-22T19:25:54+00:00",
"filters": {
"advertiser": [
"52Ax4gk6SSe9F-XXXXXXXX"
]
},
"schedule": {
"start": "2019-10-22",
"sanitized": false,
"frequency": {
"occurrence": "Weekly",
"value": "MON"
},
"end": "2019-11-01",
"emails": [
"XXXXXXXX@vistarmedia.com"
]
},
"local_end": "2020-10-01T23:59:59",
"created": "2019-10-22T19:25:54+00:00",
"local_start": "2019-10-01T00:00:00",
"groups": [
"us_state"
],
"timezone": "America/New_York",
"report_type": "exchange",
"id": "UsUnToIXS1eGHLXXXXXXXX",
"name": "Test Report 2"
}
Update and save a report
Make a call to the API to update and save a report.
URL
PUT https://staging-trafficking.vistarmedia.com/reports
PUT https://trafficking.vistarmedia.com/reports
Body parameters
See the Body parameters defined in the Create and save a report section. The following parameter must also be included in the request.
Name | Description | Type | Required | Notes | ||
id |
The unique identifier of the report. This is automatically generated after a report is first created. | string | Required |
Sample request
{
"id":"J-ijQH_vQm-XgxXXXXXXXX",
"name":"Test Report 2",
"filters":{"advertiser":["52Ax4gk6SSe9F-XXXXXXXX","8OmmrE4ySCSb7gXXXXXXXX"] },
"groups":["us_state"],
"report_type":"exchange",
"timezone":"America/New_York",
"local_end":"2020-01-23T23:59:59",
"local_start":"2020-01-17T00:00:00"
}
Sample response
{
"last_updated": "2019-01-24T16:59:18+00:00",
"filters": {"advertiser": [ "52Ax4gk6SSe9F-XXXXXXXX",
"8OmmrE4ySCSb7gXXXXXXXX"]},
"created": "2020-01-24T16:48:17+00:00",
"local_end": "2020-01-23T23:59:59",
"local_start": "2020-01-17T00:00:00",
"groups": ["us_state"],
"timezone": "America/New_York",
"report_type": "exchange",
"id": "J-ijQH_vQm-XgxXXXXXXXX",
"name": "Test Report 2"
}
Advertisers
This endpoint allows buyers who want to filter by advertiser to obtain advertiser IDs. By retrieving a list of all advertisers, you can identify the relevant ones and utilize their unique IDs to update your query. This ensures you only see information for your chosen advertisers.
To list advertiser IDs
Make a call to the Advertiser API to retrieve a list of available advertisers in Vistar’s system.
URL
GET https://staging-trafficking.vistarmedia.com/advrtsr/
GET https://trafficking.vistarmedia.com/advrtsr/
After you retrieve the advertiser IDs, use the IDs to set filters for advertisers like so:
"filters":{"advertiser":["52Ax4gk6SSe9F-XXXXXXXX"]},
Sample JSON response
[
{
"id": "2DZE1ptiTRi6PnH9u4fjeA",
"name": "Seaspan",
"is_linked": false,
"vertical_id": null
},
{
"id": "ZyyfCWpVQAqf1Nl0MC7VYA",
"name": "T-Mobile Center",
"is_linked": false,
"vertical_id": null
}
]
Buyer roles
You can apply filters, groups, or aggregations to reports depending on your user role. Additionally, you can see location-based filters that are available (see the Additional filters based on location section in this article). The following table displays the break down of which roles have access (✓) or do not have access (X) to reporting functionality.
Buyer Trafficking | Buyer Reporting & Buyer Read Only | Seller to Buyer Shared Reporting | |
Filters | ✓ | X | ✓ |
Groups | ✓ | X | ✓ |
Aggregations | ✓ | ✓ | ✓ |
See the following sections to view which filters, groups, and aggregations can be applied:
Buyer Trafficking
Filters
Filters | Description | Example |
---|---|---|
advertiser | ID of Advertiser | {"filters":{"advertiser":["NqJuHToHTv-jDHvWXkkbGg"]} |
buy_type | "deal" or "exchange" | {"filters":{"buy_type":["deal"]} |
campaign | ID of campaign | {"filters":{"campaign":["QzgQ3wn2Q2-AwhAATw4YBQ"]} |
creative | ID of creative | {"filters":{"creative": ["LJbYMtK3TUSJ-Rcb-iTvVw"]}} |
deal | ID of deal | {"filters":{"deal":["caseypackageDdealA1234"]} |
insertion_order | ID of insertion order | {"filters":{"insertion_order":["TpRr4PFOSgKMZqJp82cVYA"]} |
venue_type | Name of venue type | {"filters":{"venue_type":["Airports∣Baggage Claim"]} |
Groups
Group by | Label | Description | Example |
---|---|---|---|
advertiser_name | Advertiser | Advertiser's name | "groups":["advertiser_name"] |
buy_type | Buy type | "Exchange" or "deal" | "groups":["buy_type"] |
campaign | Campaign | Name of campaign | "groups":["campaign"] |
creative | Creative | Name of creative | "groups":["creative"] |
deal | Deal | Name of deal | "groups":["deal"] |
insertion_order | Insertion order | Name of insertion order | "groups":["insertion_order"] |
venue_type | Venue type | Malls, office buildings, and so on | "groups":["venue_type"] |
Aggregations
Aggregation | Description | Example |
---|---|---|
media_eCPM | The entire total of the average CPM you paid for impressions, based on the Media Cost only. | "media_eCPM": 5.2295086399681905 |
client_profit | The entire total of revenue minus total cost. | "client_profit": 30418.486880469114 |
client_audience_fees | The entire total of the cost of first-party or third-party audience segments. | "client_audience_fees": 16480.106826883 |
client_cost | The entire total of all media, audience, measurement, and DSP costs. | "client_cost": 818977.233394672 |
client_revenue | The entire total of tracked revenue on your campaigns. | "client_revenue": 849395.7202751415 |
data_eCPM | The entire total of CPM you paid for impressions, based on the Audience Cost only. | "data_eCPM": 0.12913722593643143 |
media_cost | The entire total of cost of media only. | "media_cost": 667374.263415008 |
impressions | The entire total of estimated number of views. | "impressions": 127617011.3410631 |
client_eCPM | The entire total of the average CPM you paid for impressions | "client_eCPM": 6.41746131482356 |
client_measurement_fees | The entire total of first-party or third-party measurement solutions. | "client_measurement_fees": 0 |
advertiser_eCPM | The entire total of revenue amount divided by the number of impressions multiplied by 1,000. | "advertiser_eCPM": 6.655818933144323 |
Buyer Reporting & Buyer Read Only
Aggregations
Aggregation | Description | Example |
---|---|---|
media_eCPM | The entire total of the average CPM you paid for impressions, based on the Media Cost only. | "media_eCPM": 5.2295086399681905 |
client_profit | The entire total of revenue minus total cost. | "client_profit": 30418.486880469114 |
client_audience_fees | The entire total of the cost of first-party or third-party audience segments. | "client_audience_fees": 16480.106826883 |
client_cost | The entire total of all media, audience, measurement, and DSP costs. | "client_cost": 818977.233394672 |
client_revenue | The entire total of tracked revenue on your campaigns. | "client_revenue": 849395.7202751415 |
data_eCPM | The entire total of CPM you paid for impressions, based on the Audience Cost only. | "data_eCPM": 0.12913722593643143 |
media_cost | The entire total of cost of media only. | "media_cost": 667374.263415008 |
impressions | The entire total of estimated number of views. | "impressions": 127617011.3410631 |
client_eCPM | The entire total of the average CPM you paid for impressions | "client_eCPM": 6.41746131482356 |
client_measurement_fees | The entire total of first-party or third-party measurement solutions. | "client_measurement_fees": 0 |
advertiser_eCPM | The entire total of revenue amount divided by the number of impressions multiplied by 1,000. | "advertiser_eCPM": 6.655818933144323 |
Seller to Buyer Shared Reporting
Filters
Filter | Description | Example |
---|---|---|
buy_type | "deal" or "exchange" | {"filters":{"buy_type":["deal"]} |
insertion_order | ID of insertion order | {"filters":{"insertion_order":["TpRr4PFOSgKMZqJp82cVYA"]} |
venue_type | Name of venue type | {"filters":{"venue_type":["Airports∣Baggage Claim"]} |
Groups
Group by | Label | Description | Example |
---|---|---|---|
buy_type | Buy Type | "Exchange" or "Deal" | "groups":["buy_type"] |
creative_name | Creative | Name of creative | "groups":["creative"] |
insertion_order | Insertion Order | Name of insertion order | "groups":["insertion_order"] |
venue_type | Venue Type | Malls, Office Buildings, etc | "groups":["venue_type"] |
Aggregations
Aggregation | Description | Example |
---|---|---|
media_eCPM | The entire total of the average CPM you paid for impressions, based on the Media Cost only. | "media_eCPM": 5.2295086399681905 |
client_profit | The entire total of revenue minus total cost. | "client_profit": 30418.486880469114 |
client_audience_fees | The entire total of the cost of first-party or third-party audience segments. | "client_audience_ |
client_cost | The entire total of all media, audience, measurement, and DSP costs. | "client_cost": 818977.233394672 |
client_revenue | The entire total of tracked revenue on your campaigns. | "client_revenue": 849395.7202751415 |
data_eCPM | The entire total of CPM you paid for impressions, based on the Audience Cost only. | "data_eCPM": 0.12913722593643143 |
media_cost | The entire total of cost of media only. | "media_cost": 667374.263415008 |
impressions | The entire total of estimated number of views. | "impressions": 127617011.3410631 |
client_eCPM | The entire total of the average CPM you paid for impressions | "client_eCPM": 6.41746131482356 |
client_measurement_fees | The entire total of first-party or third-party measurement solutions. | "client_measurement_ |
advertiser_eCPM | The entire total of revenue amount divided by the number of impressions multiplied by 1,000. | "advertiser_eCPM": 6.655818933144323 |
Additional filters based on location
Groups
Group by | Label | Description | Example |
---|---|---|---|
au_postal_area | Postal Area | AU Only |
"groups":["au_postal_area"]
|
au_state | State/Territory | AU Only |
"groups":["au_state"]
|
ca_economic_region | City | CA Account Only |
"groups":["ca_economic_region"]
|
ca_forward_sortation_area | Postal Code | CA Account Only |
"groups":["ca_forward_sortation_area"]
|
ca_province | Province | CA Account Only |
"groups":["ca_province"]
|
gb_conurbation | Conurbation | GB Account Only |
"groups":["gb_conurbation"]
|
gb_postcode_sector | Postcode Sector | GB Account Only |
"groups":["gb_postcode_sector"]
|
gb_town | Town | GB Account Only |
"groups":["gb_town"]
|
gb_tv_area | TV Area | GB Account Only |
"groups":["gb_tv_area"]
|
us_dma | DMA | US Account Only |
"groups":["us_dma"]
|
us_state | State | US Account Only |
"groups":["us_state"]
|
us_zip | Zip Code | US Account Only |
"groups":["us_zip"]
|
Status codes
The following table lists the returned HTTP status codes.
Code | Description | Notes |
200 | OK | Authentication successful. |
401 | Unauthorized | Invalid email or password. |
403 | Not Authenticated | The cookie is no longer set. User needs to reauthenticate. |