BI API overview
Recommendations for building requests
  • Always restrict requests by date: an interval of no more than 2 weeks is recommended.
  • Do not repeat identical requests more often than once every 15 minutes: data is refreshed hourly.
  • Request only the fields you actually need.
  • Do not run several requests at the same time.
1. Login
POST https://bi-v2.upravel.com/API/REST/login
Request body:
{
 "Username":"<username>",
 "Password":"<password>"
}
Response (Success):
{
 "UserName":"<username>",
 "Token":"<token for API access>"
}
Response (Fail):
{
 "Type":"access",
 "Message": "Bad username or password, please validate or try using another realm"
}
2. Logout
GET https://bi-v2.upravel.com/API/REST/<token>/logout
Response:						
{
 "Message":"Session successfully logged out"
}
3. Retrieving the list of available fields

GET https://bi-v2.upravel.com/API/REST/person/<token>/fields?platformName=<platform>
The optional `platformName` parameter should be filled in if the user has access to more than one platform.
GET https://bi-v2.upravel.com/API/REST/person/<token>/fields?platformName=<platform>
The optional platformName parameter should be filled in if the user has access to more than one platform.
Response:
{
 "Dimensions": ["daily_table", "advertiser_id", "creative_id", "publisher_id"], // grouping fields
 "Kpis": ["requests", "bids", "imps", "clicks", "ctr"]  // aggregates
}
4. Retrieving data

POST https://bi-v2.upravel.com/API/REST/person/<token>/reports/<report_id>/data/<page>/<count>

  • report_id — the parameter is not used. Kept for backward compatibility. Pass `"Traffic"`.
  • page — paging page number. Pages are numbered from 0.
  • count — number of records per page.

All dates use the `"yyyy-MM-dd"` format.

To retrieve data without pagination, use the following address:
https://bi-v2.upravel.com/API/REST/person/<token>/reports/<report_id>/data
Request body:
{
 "GroupBy":["<grouping field 1>, <grouping field 2>", ...], // required
 "StartDate":"<start of period (yyyy-MM-dd)>", // required
 "EndDate":"<end of period (yyyy-MM-dd)>", // required
 "OrderBy":[
   {"field": "<sort field>", "order":"<sort direction (asc/desc)>"},
   ...
 ],
 "Filter": [ // filters
   {
     "Field":"<field to filter on>",
     "Values":["<value1>", "<value2>", ...], // values of the same field are combined with a logical OR
     "Op":"<operator (=, <>, >, <, >=, <=, like)>"
   }, // filters on different fields are combined with a logical AND
   ...
 ],
 "DataFields":["<field1>", "<field2>", ...], // required. List of requested fields.
 "Timezone":180, // Optional. The time zone the data should be returned in (in minutes relative to UTC; 180 = UTC+3). Available on specific platforms only.
 "PlatformName":"<platform_name>" // Optional. Fill in if the user has access to more than one platform.
}
Response (Success):
{
 "Total":{
   "DataCount": [
     {
       "Field":"<field name>",
       "Value":"<field value>"
     },
     ...
   ],
   "RecCount":<total number of distinct values of the field specified in GroupBy>
 },
 "Data": [
   {
     "DataFields": [
       {"Field":"<field name>", "Value":"<field value>"    },
       ...
     ],
     "GroupingFields": [
       {"Field":"<grouping field 1>","Value":"<value>"},
       {"Field":"<grouping field 2>","Value":"<value>"},
       …
     ]
   },
   ...
 ]
}

Response (if required fields are missing or non-existent data fields are used):
{
 "Type": "exception",
 "Message": "<message explaining the error>"
}

Response (if the token is invalid):
{
 "Type": "access",
 "Message": "Token invalid"
}
Sample request:
{
 "GroupBy": ["placement_id"],
 "StartDate": "2014-01-01",
 "EndDate": "2014-01-07",
 "DataFields": ["bids", "imps", "clicks", "adv_payout", "pub_payout"],
 "Filter": [{
   "Field": "publisher_id", "Values": [41], "Match": "equals"
 }]
}

Sample response:
{
 "Total": {
   "DataCount": [
     {"Field": "bids", "Value": "12345678"},
     {"Field": "imps", "Value": "1365872" },
     {"Field": "clicks", "Value": "21621"},
     {"Field": "adv_payout", "Value": "30733.028700000148"},
     {"Field": "pub_payout", "Value": "0.0"}
   ],
   "RecCount": 1
 },
 "Data": [
   {
     "DataFields":
     [
       {"Field": "bids", "Value": "12345678"},
       {"Field": "imps", "Value": "1365872" },
       {"Field": "clicks", "Value": "21621"},
       {"Field": "adv_payout", "Value": "30733.028700000148"},
       {"Field": "pub_payout", "Value": "0.0"}
     ],
     "GroupingFields":
     [
       {"Field":"placement_id","Value":"1519"}
     ]
   }
 ]
}
5. Retrieving platform information

GET https://bi-v2.upravel.com/API/REST/person/<token>/platform?platformName=<platform>`
platform — the name of the platform to get information about. If the parameter is omitted, the first available platform is returned.
Response (Success):
{
 "Dimensions": [ // available grouping fields
   {
     "field": "campaign_id", // "technical" field name
     "group_id": 1, // field group identifier
     "editable": false, // whether the field value can be edited
     "filter_only": false, // whether the field can only be used for filtering and not for grouping
     "names": { // human-readable field names in the platform's available languages
       "ru": "Id кампании",
       "en": "Campaign Id"
     }
   }, ...
 ],
 "Kpis": [
   // same structure as Dimensions
 ],
 "Groups": [1], // field group identifiers
 "Widgets": [ // UI widgets available for the platform
   "table",
   "chart",
   "offline_reports"
 ],
 "Languages": [ // languages supported by the platform
   "ru",
   "en"
 ],
 "Timezones": [], // Time zones for which full platform data is available. Not supported by most platforms.
 "Editable": false, // whether platform data can be edited
 "Names": { // human-readable platform names in the platform's available languages
   "ru": "DSP",
   "en": "DSP"
 }
}