DSP Reporting API

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

Staging Production
POST https://staging.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

Staging Production
GET https://staging-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"
    }

...

]

Back to top

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

Staging Production
POST https://staging-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:

  • exchange
  • shared
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: 2019-03-22T00:00:00

string Required  
local_end

The date and time in the specified timezone.

For example: 2019-03-28T23:59:59

string Required  
end* Date and time using ISO 8601 format. string Deprecated

*It is recommended to not use this field.

You must use the local_end field going forward

start* Date and time using ISO 8601 format. string Deprecated

*It is recommended to not use this field.

You must use the local_start field going forward.

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"

Back to top

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

Staging Production
POST https://staging-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:

  • exchange
  • shared
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: 2019-03-22T00:00:00

string Required  
local_end

The date and time in the specified timezone.

For example: 2019-03-28T23:59:59

string Required  
end* Date and time using ISO 8601 format. string Deprecated

*It is recommended to not use this field.

You must use the local_end field going forward.

start* Date and time using ISO 8601 format. string Deprecated

*It is recommended to not use this field.

You must use the local_start field going forward.

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:

  • None
  • Daily
  • Weekly
  • Monthly
  • Quarterly

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 occurrence field), you must enter the corresponding value:

  • MON
  • TUE
  • WED
  • THU
  • FRI
  • SAT
  • SUN

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:

  • true—Send a limited report.
  • false—Send a standard report.
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"
    }

Back to top

Update and save a report

Make a call to the API to update and save a report.

URL

Staging Production
PUT https://staging-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"
}

Back to top

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

Staging Production
GET https://staging-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
    }
]

Back to top

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

Back to top

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

Back to top

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_
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

Back to top

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

Back to top

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.

Back to top

Was this article helpful?
2 out of 7 found this helpful