Platform API

Primis Platform API is a tool for third-party developers, which allows integration with Primisโ€™ backend data to their systems. Currently, this API provides the following capabilities:

  • Reporting (e.g., impressions, revenue, RPM / eCPM etc.)

๐Ÿ“˜

How to work with Primis Platform API

Check this walkthrough here for a quick explanation.

API Architecture
The Primis Platform API is implemented as an API over the HTTPS protocol and returns (by default) JSON data format.

API Versioning
Primis releases versions of this API in accordance with the following rule to protect the users from integration problems that may occur in the future.

  • It is guaranteed that changes within the same major version of the API (e.g., 1.00, 1.10, etc.) will not break your integration and will only fix defects or add minor feature enhancements or changes.
  • Major version changes (e.g., 2.00, 3.00, etc.) may introduce some significant changes that may require some coding changes to your integration. In other words, integrations written to be used with version 1.0 may not work with version 2.0 or 3.0, without possible significant changes.

Connections
Connections to Primis API are only accessible via the HTTPS protocol.

Errors
Primis Platform API returns errors in standard HTTP status codes (usually client error codes, e.g. 4XX status codes). See the Errors Description section of this document for details for each error returned by the service.

Authentication

All interactions with Primis Platform API must be authenticated. An API client can be authenticated by the platform by performing an initial login request using an API User Name and Code. This login request will return a token code and the calling client must send this token code in all other service requests.

  • To access the Primis Platform API, the calling system must authenticate and use the authentication token in subsequent API requests.

  • To receive credentials for Primis Platform API, contact your assigned account manager.

  • Tokens will be renewed daily - every 24 hours

    • After this time the user must re-authenticate using Step 1 as described below.

The Authentication service uses HTTPS GET method.

Step 1: To perform the authentication you need to send a GET request:

curl "https://console.primis.tech/UI/php/responders/apiResponder.php?method=authentication&apiUserName=[API_USER_NAME]&apiUserCode=[API_USER_CODE]&version=2.19"

Primis Platform API responds with a JSON containing your API access token:

{"token":" XXXXXXXXXXXXX "}

Reporting Service

The reporting service is a non-blocking service. The service is providing statistical data by chosen granularity (e.g. browser, OS, specific placement, etc.) In the current version, the service provides Primis Publisher Reports by the appropriate method, as is shown below.

Request
To receive the report data, you need to send 2 commands consequentially:

Step 1: Posting a report request which includes a token, version, method and JSON formatted filters. Hereupon, the API will return a unique โ€˜Report IDโ€™.

For more information regarding the possible filters, their description and syntax, see the Report Request Filters section. For the full filter list, see the Reference: Filters Description section of the current document.

An example:

curl -X POST -d 'token=XXXXXXXXXXXXX&version=2.19&method=publisherReport&data=[{"name":"filter1","data":["nnn"]},{"name":"filter2","data":"123"}]' -f https://console.primis.tech/UI/php/responders/apiResponder.php

Token = XXXXXXXXXXXXX
Version = 2.19
Method = publisherReport
Data =
[
{"name":"filter1","data":["nnn"]},
{"name":"filter2","data":"123"}
]

A report ID is returned as an answer:

{"reportId":"0123456789"}

Step 2: Requesting report data by Report ID, which consists of token, version, method and report ID.
A command example:

curl --data "token=XXXXXXXXXXXXX&version=2.19&method=publisherReport&reportId=0123456789" -f https://console.primis.tech/UI/php/responders/apiResponder.php

Token = XXXXXXXXXXXXX
Version = 2.19
Method = publisherReport
Report ID = 0123456789

Response
After the request (Step 2), The API will return a response.

The response is represented as an array of element objects in JSON format, where objects are defined by your requested dimensions and set of fields inside an element are set by the metrics in your request. The returned report data depends on your selected filters that were set in Step 1.

  • When the data is ready, the Primis Platform API will return the requested data (200).
  • When data is received properly the API will return 'Report not found' (404)
  • If the report data is not yet ready, the API will return โ€˜Data is not readyโ€™ (454) error. In such case please repeat Step 2 several minutes later.

Data example:

[
โ€ƒ{
โ€ƒโ€ƒ"placement":1111,
โ€ƒโ€ƒ"placementName":"Placement Name1",
โ€ƒโ€ƒ"placement_imps":1111,
โ€ƒโ€ƒ"rpm":0.1,
โ€ƒโ€ƒ"revenue":11.11
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"placement":2222,
โ€ƒโ€ƒ"placementName":"Placement Name2",
โ€ƒโ€ƒ"placement_imps":2222,
โ€ƒโ€ƒ"rpm":0.2,
โ€ƒโ€ƒ"revenue":22
โ€ƒ }
]

Note: The time zone and currency of the report data are the accountโ€™s default time zone and currency.

Report Request Filters
The report request filters are designed to determine the resulting data. Each filter must consist of a name, data and optional include/exclude parameter.

The data field of a filter might be either a single value or an array of values depending on the filter. The exclude field should be set to โ€˜1โ€™ (exclude) or โ€˜0โ€™ (include).

All the API filters can be divided into several groups by their meaning:

1. Report Type
(API name: โ€reportTypeโ€)
This filter determines which report you can get. Report type might be: Media, Ad Server, Content, Syndication or Billing.
Each report type has its own set of metrics and dimensions.

2. Dimensions
(API name: โ€dimensionsโ€)
The dimensions filter determines the desirable objects in your report response, i.e. what objects are needed to be โ€œgrouped byโ€. Placement, Campaign, Browser and Country are dimension examples. Each report type has its own dimensions set.

3. Metrics
(API name: โ€metricsโ€)
Metrics are different types of quantitative measurement parameters, by which Primis collects statistics, e.g. Attempts, Impressions or Revenue

4.Object Filters
(all other filters)
All other available filters are optional and are used to filter the report data, i.e. to see only such data you want to be displayed, whether it is a specific set of your placements or statistical data for a specific country.

For the full filter list and its parameters, see the Filters Description section in Reference.

Report Types

Media Report
A Media Report is a generic report type that provides statistics in different levels of granularity from the media side. To have access to the Media Report type, your Primis account must be setup as Publisher`s account.

Media Reports support the following dimensions: placement; player type; media type; placement size; browser; operating system; operating system version; country; device type; domain; total; time interval and sub ID. Please note that the 'total' dimension can't be used in combination with any other, but only as a single dimension.

Its metrics are (API names are given in parentheses): ID and name (id and name metrics will return the corresponded dimension data); placement impressions (placement_imps); revenue (revenue); revenue RPM (rpm); Ad Server video impressions from publisher`s Ad Server campaigns (video_adserver_imps); Ad Server video revenue (video_adserver_revenue); revenue from the Primis Marketplace side (video_primis_revenue); Ad Server video eCPM (video_adserver_cpm) and others.

For the full list of filters and their syntax and parameters see the Filter Descriptions section in Reference.

A request example:

curl -X POST -d 'token=XXXXXXXXXXXXX&version=2.19&method=publisherReport&data=[{"name":"reportType","data":"media"},{"name":"timeZone","data":"us_eastern"},{"name":"dimensions","data":["browser"]},{"name":"period","data":"lastMonth"},{"name":"metrics","data":["id","name","placement_imps","rpm","revenue"]}]' -f https://console.primis.tech/UI/php/responders/apiResponder.php

A response example:

[
โ€ƒ{
โ€ƒโ€ƒ"deviceTypeId":"smartphone_web",
โ€ƒโ€ƒ"placement_imps":1111,
โ€ƒโ€ƒ"rpm":0.1,
โ€ƒโ€ƒ"revenue":11.11
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"deviceTypeId":"Desktop",
โ€ƒโ€ƒ"placement_imps":22222,
โ€ƒโ€ƒ"rpm":2.2,
โ€ƒโ€ƒ"revenue":222
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"deviceTypeId":"tablet_app",
โ€ƒโ€ƒ"placement_imps":33333,
โ€ƒโ€ƒ"rpm":3.3,
โ€ƒโ€ƒ"revenue":333.33
โ€ƒ},
]

Ad Server Report
An Ad Server report is a video statistic report adjusted to provide granularity for Ad Server campaigns. The Ad Server report requires an Ad Server access for your Primis account.

The Ad Server report`s dimensions are: media placement; media type; campaign; browser; placement size; player type; operating system; operating system version; hb partner; country; device type; domain; total and time interval. Please note that the 'total' dimension can't be used in combination with any other, but only as a single dimension.

Its metrics are (API names are given in parentheses): ID and name (id and name metrics will return the corresponded dimension data); video ad impressions (ad_imps); eCPM (ad_cpm); revenue (ad_revenue); percent of viewable impressions (ad_viewability_rate); ad attempts (ad_attempts); completion rate (ad_vtr) and fillrate (ad_fillrate); Ad Server Commission Fee (serving_fee) and others.

For the full list of filters and their syntax and parameters see the Filter Descriptions section in Reference.

A request example:

curl -X POST -d 'token=XXXXXXXXXXXXX&version=2.19&method=publisherReport&data=[{"name":"reportType","data":"adServer"},{"name":"timeZone","data":"us_eastern"},{"name":"dimensions","data":["browser"]},{"name":"period","data":"custom"},{"name":"fromDay","data":"2018-10-20"},{"name":"toDay","data":"2018-10-21"},{"name":"timeInterval","data":"cumulative"},{"name":"metrics","data":["id","name","ad_imps","ad_cpm","ad_revenue"]}]' -f https://console.primis.tech/UI/php/responders/apiResponder.php

A response example:

[
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Mobile Application",
โ€ƒโ€ƒ"ad_imps":1111,
โ€ƒโ€ƒ"ad_cpm":1.1,
โ€ƒโ€ƒ"ad_revenue":11.11
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Chrome",
โ€ƒโ€ƒ"ad_imps":2222,
โ€ƒโ€ƒ"ad_cpm":2.2,
โ€ƒโ€ƒ"ad_revenue":222.22
โ€ƒ},
]

Content Report
A Content report is a content statistic report. To have access to the Content Report type, your Primis account must be setup as Publisher`s account.

The Content report`s dimensions are: placement; placement size; media type; content channel; channel category; content creator; content file; browser; operating system; operating system version; country; device type; domain; total and time interval. Please note that the 'total' dimension can't be used in combination with any other, but only as a single dimension.

Its metrics are (API names are given in parentheses): ID and name (id and name metrics will return the corresponded dimension data); content impressions (content_imps); content eCPM (content_ecpm); playlist click rate (content_playlist_click_rate); complete rate (content_complete_rate); likes (content_likes); pause click rate (content_pause_click_rate) and others.

For the full list of filters and their syntax and parameters see the Filter Descriptions section in Reference.

A request example:

curl -X POST -d 'token=XXXXXXXXXXXXX&version=2.18&method=publisherReport&data=[{"name":"reportType","data":"content"},{"name":"timeZone","data":"us_eastern"},{"name":"dimensions","data":["browser"]},{"name":"period","data":"yesterday"},{"name":"timeInterval","data":"cumulative"},{"name":"metrics","data":["id","name","content_imps"]}]' -f https://console.primis.tech/UI/php/responders/apiResponder.php

A response example:

[
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Mobile Application",
โ€ƒโ€ƒ"content_imps":1111,
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Chrome",
โ€ƒโ€ƒ"content_imps":2222,
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Opera",
โ€ƒโ€ƒ"content_imps":3333,
โ€ƒ},
]

Syndication Report
A Syndication report is a syndication content statistic report. To have access to the Syndication Report type, your Primis account must be setup as Publisher`s account.

The Syndication report`s dimensions are: country; media type; content channel; channel category; content file; browser; operating system; domain; total and time interval. Please note that the 'total' dimension can't be used in combination with any other, but only as a single dimension.

Its metrics are (API names are given in parentheses): ID and name (id and name metrics will return the corresponded dimension data); content impressions (content_imps); content eCPM (content_ecpm); playlist click rate (content_playlist_click_rate); complete rate (content_complete_rate); likes (content_likes); pause click rate (content_pause_click_rate) and others.

For the full list of filters and their syntax and parameters see the Filter Descriptions section in Reference.

A request example:

curl -X POST -d 'token=XXXXXXXXXXXXX&version=2.19&method=publisherReport&data=[{"name":"reportType","data":"syndication"},{"name":"timeZone","data":"us_eastern"},{"name":"dimensions","data":["browser"]},{"name":"period","data":"yesterday"},{"name":"timeInterval","data":"cumulative"},{"name":"metrics","data":["id","name","content_imps"]}]' -f https://console.primis.tech/UI/php/responders/apiResponder.php

A response example:

[
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Mobile Application",
โ€ƒโ€ƒ"content_imps":1111,
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Chrome",
โ€ƒโ€ƒ"content_imps":2222,
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"browserId":"Opera",
โ€ƒโ€ƒ"content_imps":3333,
โ€ƒ},
]

Billing Report
A Billing Report is a report type that provides billing data, similar to the Billing page of the Primis system. The Billing Report requires Ad Server access for your Primis account.
Except for the Report Type, no other filters are necessary for the Billing Report. All other filters in the request will be ignored.

A request example:

curl --data 'token=XXXXXXXXXXXXX&version=2.19&method=publisherReport&data=[{"name":"reportType","data":"billing"}]' -f https://console.primis.tech/UI/php/responders/apiResponder.php

As a response, the API will return the user`s billing data under the fixed metrics.

Below you can find the set of metrics.

NameAPI NameFormat
Period start datestartDateDate: yyyy-mm-dd
Period end dateendDateDate: yyyy-mm-dd
Payment statusstatusString
Ad Server RevenueadServerRevenueDecimal
Primis RevenueprimisRevenueDecimal
Total RevenuetotalRevenueDecimal
Ad Serving FeeadServingFeeDecimal
Payment DatepaymentDateDate: yyyy-mm-dd
Net BillingnetBillingDecimal

A response example:

[
โ€ƒ{
โ€ƒโ€ƒ"startDate":"2018-11-01",
โ€ƒโ€ƒ"endDate":"2018-11-24",
โ€ƒโ€ƒ"status":"openPeriod",
โ€ƒโ€ƒ"adServerRevenue":0,
โ€ƒโ€ƒ"primisRevenue":0,
โ€ƒโ€ƒ"totalRevenue":0,
โ€ƒโ€ƒ"adServingFee":0,
โ€ƒโ€ƒ"paymentDate":"-",
โ€ƒโ€ƒ"netBilling:0
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"startDate":"2018-10-01",
โ€ƒโ€ƒ"endDate":"2018-10-31",
โ€ƒโ€ƒ"status":"invoiceReceived",
โ€ƒโ€ƒ"adServerRevenue":1967.63,
โ€ƒโ€ƒ"primisRevenue":4990.93,
โ€ƒโ€ƒ"totalRevenue":6958.55,
โ€ƒโ€ƒ"adServingFee":977.07,
โ€ƒโ€ƒ"paymentDate":"2018-11-26",
โ€ƒโ€ƒ"netBilling:2013.86
โ€ƒ},
โ€ƒ{
โ€ƒโ€ƒ"startDate":"2018-09-01",
โ€ƒโ€ƒ"endDate":"2018-09-31",
โ€ƒโ€ƒ"status":"paid",
โ€ƒโ€ƒ"adServerRevenue":365.12,
โ€ƒโ€ƒ"primisRevenue":3251.19,
โ€ƒโ€ƒ"totalRevenue":6616.31,
โ€ƒโ€ƒ"adServingFee":80.21,
โ€ƒโ€ƒ"paymentDate":"2018-11-01",
โ€ƒโ€ƒ"netBilling:2570.98
โ€ƒ},
]

Reference

NameDescription
authenticationInitial authentication
publisherReportFor publisherโ€™s reporting service

Filter Descriptions


{
  "data": {
    "h-0": "Filter Name",
    "h-1": "Values",
    "h-2": "Field Req.",
    "h-3": "Filter Type",
    "h-4": "Default Value",
    "h-5": "Exclude Option",
    "h-6": "Report Type Req.",
    "0-0": "<b>timeInterval</b>",
    "0-1": "<ul><li>cumulative</li><li>hour</li><li>date</li><li>week</li><li>month</li></ul>",
    "0-2": "n",
    "0-3": "Single (string)",
    "0-4": "cumulative",
    "0-5": "n",
    "0-6": "Media, Ad Server,  \nContent, Syndication",
    "1-0": "<b>timeZone</b>",
    "1-1": "<ul><li>us_pacific</li><li>us_eastern</li><li>us_mountain</li><li>eu_moscow</li><li>eu_london</li><li>eu_central</li><li>au_sydney</li><li>asia_tokyo</li><li>asia_israel</li><li>utc+0</li><li>utc-5</li></ul>",
    "1-2": "y",
    "1-3": "Single (string)",
    "1-4": "cumulative",
    "1-5": "n",
    "1-6": "Media, Ad Server,  \nContent, Syndication",
    "2-0": "<b>period</b>",
    "2-1": "<ul><li>today</li><li>yesterday</li><li>currentMonth</li><li>lastMonth</li><li>custom</li></ul><i>Note: If 'custom' value is selected, the filters fromDay and toDay are required.</i>",
    "2-2": "y",
    "2-3": "Single (string)",
    "2-4": "No Default",
    "2-5": "n",
    "2-6": "Media, Ad Server,  \nContent, Syndication",
    "3-0": "<b>fromDay</b>",
    "3-1": "From date, in format yyyy-mm-dd in case of 'period' is set to 'custom'.",
    "3-2": "y",
    "3-3": "Single (string)",
    "3-4": "No Default",
    "3-5": "n",
    "3-6": "Media, Ad Server,  \nContent, Syndication",
    "4-0": "<b>toDay</b>",
    "4-1": "To date, in format yyyy-mm-dd in case of 'period' is set to 'custom'.",
    "4-2": "y",
    "4-3": "Single (string)",
    "4-4": "No Default",
    "4-5": "n",
    "4-6": "Media, Ad Server,  \nContent, Syndication"
  },
  "cols": 7,
  "rows": 5,
  "align": [
    "left",
    "left",
    "left",
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

Timeframe Filters


{
  "data": {
    "h-0": "Filter Name",
    "h-1": "Values",
    "h-2": "Field Req.",
    "h-3": "Filter Type",
    "h-4": "Default Value",
    "h-5": "Exclude Option",
    "h-6": "Report Type Req.",
    "0-0": "<b>timeInterval</b>",
    "0-1": "<ul><li>cumulative</li><li>hour</li><li>date</li><li>week</li><li>month</li></ul>",
    "0-2": "n",
    "0-3": "Single (string)",
    "0-4": "cumulative",
    "0-5": "n",
    "0-6": "Media, Ad Server,  \nContent, Syndication",
    "1-0": "<b>timeZone</b>",
    "1-1": "<ul><li>us_pacific</li><li>us_eastern</li><li>us_mountain</li><li>eu_moscow</li><li>eu_london</li><li>eu_central</li><li>au_sydney</li><li>asia_tokyo</li><li>asia_israel</li><li>utc+0</li><li>utc-5</li></ul>",
    "1-2": "y",
    "1-3": "Single (string)",
    "1-4": "cumulative",
    "1-5": "n",
    "1-6": "Media, Ad Server,  \nContent, Syndication",
    "2-0": "<b>period</b>",
    "2-1": "<ul><li>today</li><li>yesterday</li><li>currentMonth</li><li>lastMonth</li><li>custom</li></ul><i>Note: If 'custom' value is selected, the filters fromDay and toDay are required.</i>",
    "2-2": "y",
    "2-3": "Single (string)",
    "2-4": "No Default",
    "2-5": "n",
    "2-6": "Media, Ad Server,  \nContent, Syndication",
    "3-0": "<b>fromDay</b>",
    "3-1": "From date, in format yyyy-mm-dd in case of 'period' is set to 'custom'.",
    "3-2": "y",
    "3-3": "Single (string)",
    "3-4": "No Default",
    "3-5": "n",
    "3-6": "Media, Ad Server,  \nContent, Syndication",
    "4-0": "<b>toDay</b>",
    "4-1": "To date, in format yyyy-mm-dd in case of 'period' is set to 'custom'.",
    "4-2": "y",
    "4-3": "Single (string)",
    "4-4": "No Default",
    "4-5": "n",
    "4-6": "Media, Ad Server,  \nContent, Syndication"
  },
  "cols": 7,
  "rows": 5,
  "align": [
    "left",
    "left",
    "left",
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

Object Filters


{
  "data": {
    "h-0": "Filter Name",
    "h-1": "Values",
    "h-2": "Field Req.",
    "h-3": "Filter Type",
    "h-4": "Default Value",
    "h-5": "Exclude Option",
    "h-6": "Report Type Req.",
    "0-0": "<b>timeInterval</b>",
    "0-1": "<ul><li>cumulative</li><li>hour</li><li>date</li><li>week</li><li>month</li></ul>",
    "0-2": "n",
    "0-3": "Single (string)",
    "0-4": "cumulative",
    "0-5": "n",
    "0-6": "Media, Ad Server,  \nContent, Syndication",
    "1-0": "<b>timeZone</b>",
    "1-1": "<ul><li>us_pacific</li><li>us_eastern</li><li>us_mountain</li><li>eu_moscow</li><li>eu_london</li><li>eu_central</li><li>au_sydney</li><li>asia_tokyo</li><li>asia_israel</li><li>utc+0</li><li>utc-5</li></ul>",
    "1-2": "y",
    "1-3": "Single (string)",
    "1-4": "cumulative",
    "1-5": "n",
    "1-6": "Media, Ad Server,  \nContent, Syndication",
    "2-0": "<b>period</b>",
    "2-1": "<ul><li>today</li><li>yesterday</li><li>currentMonth</li><li>lastMonth</li><li>custom</li></ul><i>Note: If 'custom' value is selected, the filters fromDay and toDay are required.</i>",
    "2-2": "y",
    "2-3": "Single (string)",
    "2-4": "No Default",
    "2-5": "n",
    "2-6": "Media, Ad Server,  \nContent, Syndication",
    "3-0": "<b>fromDay</b>",
    "3-1": "From date, in format yyyy-mm-dd in case of 'period' is set to 'custom'.",
    "3-2": "y",
    "3-3": "Single (string)",
    "3-4": "No Default",
    "3-5": "n",
    "3-6": "Media, Ad Server,  \nContent, Syndication",
    "4-0": "<b>toDay</b>",
    "4-1": "To date, in format yyyy-mm-dd in case of 'period' is set to 'custom'.",
    "4-2": "y",
    "4-3": "Single (string)",
    "4-4": "No Default",
    "4-5": "n",
    "4-6": "Media, Ad Server,  \nContent, Syndication"
  },
  "cols": 7,
  "rows": 5,
  "align": [
    "left",
    "left",
    "left",
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

Filter NameValuesField Req.Filter TypeDefault ValueExclude OptionReport Type Req.
countryFilter

For the values see the table 'Country Codes'.

Example:

{"name":"countryFilter","data":["55","30"]}
nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
regionFilter
  • na
  • eu
  • mena
  • apac
  • latam
  • other
nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
domainFilter

Domain

Example:

{"name":"domainFilter","data":"yadoo.com,bulik.tr"}
nSingle (string)AllyMedia, Ad Server,
Content, Syndication
browserFilter
  • chrome
  • firefox
  • safari
  • edge
  • opera
  • fbapp
  • papp
  • app
  • man
  • other
Note: man - manufacture native browser.
nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
osFilter
  • windows
  • linux
  • macosx
  • chromeos
  • ios
  • android
  • other
nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
deviceTypeFilter
  • desktop
  • smartphone_app
  • smartphone_web
  • tablet_app
  • tablet_web
  • bot
  • ctv
nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
playerTypeFilter
  • normal
  • flow
  • sticky
  • inRead
  • slider
  • inUnit
nMultiply (array)AllnMedia, Ad Server
inventoryTypeFilter
  • amp
  • desktop
  • app
nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
campaignLabelFilter
  • Open Marketplace
  • Private Marketplace
  • Programmatic Guaranteed
  • Private Deal
  • Other
nMultiply (array)AllyAd Server
placementFilter

Placement Ids

Example:

{"name":"placementFilter","data":["4500","45001"]}

nMultiply (array)AllyMedia, Ad Server,
Content, Syndication
minImpsFilterDetermines the min. number of imp. by which data will be filtered.nSingle (string)0yMedia, Content,
Syndication
campaignFilter

Campaign Ids

Example:

{"name":"campaignFilter","data":["75862","784","627"]}

nMultiply (array)AllyAd Server
contentChannelFilter

Content Channel Ids

Example:

{"name":"contentChannelFilter","data":["5694","1234","82"]}

nMultiply (array)AllyContent, Syndication
channelCategoryFilter

Content File Ids

Example:

{"name":"contentFileFilter","data":["73286","12769","5818"]}

nMultiply (array)AllyContent, Syndication
contentFileFilter

Content File Ids

Example:

{"name":"contentFileFilter","data":["73286","12769","5818"]}

nMultiply (array)AllyContent, Syndication
contentCreatorFilter

Content Creator Ids

Example:

{"name":"contentCreatorFilter","data":["8754","284","516"]}

nMultiply (array)AllyContent
viewHBPartnerFilter

For the values see the table 'HB Partner Codes'.

Example:

{"name":"viewHBPartnerFilter","data":["59","82"]}

nMultiply (array)AllyAd Server
foldDomainFilter

Fold domains.

Example:

{"name":"foldDomainFilter","data":"true"}

nBooleanNonMedia, Ad Server,
Content, Syndication
minContentStartsFilter

Min. Content Starts.

Example:

{"name":"contentStartsCountFilter","data":"6"}

nBooleanNonContent, Syndication

Metric Descriptions

Media Report

MetricDescription
placement_impsNumber of Player Loads
placement_unq_impsNumber of unique player users
revenueTotal revenue of the Unit
rpmNET Revenue per 1000 player loads
video_adserver_impsTotal number of Ad Impressions from Publishers Ad Server
video_primis_impsTotal number of Ad Impressions from Primis Marketplace
video_total_impsTotal number of Video Ad Impressions
video_adserver_revenueTotal Revenue from Publishers Ad Server
video_primis_revenueNet revenue from Primis marketplace
video_adserver_cpmThe Video Ad CPM of Publisher's Adserver
video_primis_cpmThe Video Ad CPM of Primis marketplace
video_adserver_serving_feeServing fee commission on served Video Ads of Publisher's Adserver
placement_ivt_hidden_rateMeasure technical issues that prevented from the player to load
placement_avg_durationTime spent on page (in seconds)
placement_viewable_avg_durationTime spent on page while player was in view (seconds)
gdpr_consent_ratePercentage of GDPR consents passed to Primis per Placement Imps.
float_close_ratePercentage of users who closed the Float unit
placement_engagement_rateHow many users engage with the content (click on the sound, full screen, likes, etc)
placement_viewability_ratePercentage of Viewable player loads (2 seconds, +50% pixels on view)
placement_ifa_pass_rateIdentifier for Advertising (app related only)
placement_video_fillrateVideo Ad Impressions per Placement Imps (Player Load)
content_impsNumber of Video Content Starts
placement_content_fillrateContent Imps starts per Placement Imps (Player Load)
content_vtrPercentage of users who watched a video for at least 30 seconds

Ad Server Report

MetricDescription
ad_impsServed Video Ad Impressions
ad_revenueRevenue
ad_cpmCPM
ad_clicksClicks
ad_viewability_rateVideo Ad impressions viewability as declared by MRC
ad_attemptsNumber of Ad Calls that were sent to the SSP/Exchange
ad_attempt_ecpmThe eCPM of ad attempts. equal to Revenue/Attempts*1000
ad_response_rateNon-empty valid responses
ad_ctrCTR(%)
ad_vtrThe percentage of Video Ad imps that played to completion
ad_fillrateVideo Ad Imps / Attempts
ad_success_rateVideo Imps / Responses
ad_responsesResponses / Attempts
serving_feeVideo Ads Serving fee commission
ad_win_rateThe percentage of impression that won in auctions. equal to wins/responses*100

Content Report

MetricDescription
content_impsNumber of Video Content Starts
content_guidVideo ID provided by the publisher/content provider
content_full_screen_ratePercentage of users enabling Full-screen
content_volume_change_ratePercentage of users enabling Sound On
content_playlist_click_ratePercentage of users clicking on the Playlist Thumbnails
content_timeline_change_ratePercentage of users changing the video timeline
content_complete_ratePercentage of content impressions completed
content_vtrPercentage of users who watched a video for at least 30 seconds
content_pause_click_ratePercentage of users who paused the video
content_likesNumber Likes by users on Primis platform
content_ctrCTR(%)
content_clicksNumber of Video Content Clicks
content_engagement_ratePercentage of all users engage metrics (click on the sound, full screen, likes, etc)

Syndication Program Report

MetricDescription
content_guidVideo ID provided by the publisher/content provider
content_revenueRevenue generated from the video
content_ecpmThe effective CPM generated from the video
content_impsNumber of Video Content Starts
content_clicksNumber of Video Content Clicks
content_ctrCTR(%)
content_full_screen_ratePercentage of users enabling Full-screen
content_volume_change_ratePercentage of users enabling Sound On
content_playlist_click_ratePercentage of users clicking on the Playlist Thumbnails
content_timeline_change_ratePercentage of users changing the video timeline
content_engagement_ratePercentage of all users engage metrics (click on the sound, full screen, likes, etc)
content_likesNumber Likes by users on Primis platform
content_complete_ratePercentage of users who watched the video till the end
content_vtrPercentage of users who watched a video for at least 30 seconds
content_pause_click_ratePercentage of users who paused the video

Country Codes

ValueDescription
74Argentina
77Australia
78Austria
85Belgium
56Brazil
96Bulgaria
31Canada
105Chile
106China
109Colombia
114Costa Rica
119Czech Republic
120Denmark
134Finland
61France
57Germany
143Greece
156Hong Kong
157Hungary
159India
160Indonesia
163Ireland
25Israel
164Italy
166Japan
188Malaysia
63Mexico
58Netherlands
210New Zealand
217Norway
55Other
222Panama
226Philippines
228Poland
229Portugal
60Romania
59Russian Federation
224Serbia
247Singapore
252South Africa
64Spain
259Sweden
260Switzerland
262Taiwan
265Thailand
272Turkey
278United Arab Emirates
62United Kingdom
30United States
284Vietnam

Channel Category Codes

ValueDescription
1Automotive
42Books and Literature
52Business & Finance
123Careers
132Education
150Events and Attractions
186Family and Relationships
201Fine Art
210Food & Drink
223Healthy Living
239Hobbies & Interests
274Home & Garden
286Medical Health
324Movies
338Music and Audio
379News and Politics
391Personal Finance
422Pets
432Pop Culture
441Real Estate
453Religion & Spirituality
464Science
473Shopping
483Sports
1007Social
552Style & Fashion
596Technology & Computing
640Television
653Travel
680Video Gaming

HB Partner Codes

ValueDescription
0Regular Tag (no HB)
16FreeWheel
36Appnexus
45Smart
49Pulse Point
50OpenX
60Pubmatic
67Gumgum
72RhythemOne
74Rubicon
75Google AdX
78Telaria
80oneVideo
81General
82AmazonA9
83IndexExchange
87EMXDigital
90Verizon S2S
91Pubmatic S2S
92Bidswitch RTB
93LoopMe S2S
94SpotX S2S
98OpenX S2S
99Index S2S
100Rubicon S2S
101Media.net
102Triplelift
103Boldwin
104Adman
105Xandr S2S
106Undertone
107Colossus
110Yielmdo
11133Across
112The Media Grid
113Mobile Fuse S2S
114Smartadserver S2S
115Pulsepoint S2S
117Yahoo SSP
118Tappx
119Unruly S2S
121TripleLift
124Opera Ads
125Sharethrough
126Telaria
127Media.Net S2S
128Yahoo S2S
129Epsilon S2S
130Sovrn S2S
131Sonobi
132Turk Telekom
133Kargo
134FreeWheel S2S
135SmartX
136MinuteMedia
137RichAudience
138Adman S2S
140Smart S2S

Error Descriptions

HTTP Error CodeStatusDescription
450UnauthorizedAPI user name is incorrect or doesn't exist
451Bad TokenToken is incorrect or expired
452Method Not AllowedInvalid method
453Validation ErrorInvalid filter(s)
454Data Is Not ReadySystem doesn`t finish the data preparation
455Bad VersionThe API version is absent, obsolete or incorrect
456No PermissionNo permission to retrieve the report
457Limit ExceededThe user has sent too many requests in a given amount of time (rate limiting).

API Viewer

For your convenience, you can use the API Viewer in your Reports tab.
For further assistance, please contact your Primis representative.

1920 866