Traffic Report API v2
1. Introduction
The HORISEN Traffic Report API is used for bulk traffic reports.
This API returns information about the traffic, the number of sent messages, the price per message and the total amount for each pricing condition, country, operator and selling/buying price.
This API belongs to the Traffic Report domain. The subject domain of an endpoint URL is:
https://api{separator}{platform_domain}/bulk/traffic-report/v2
Note: A domain is presented with placeholders as https://api{separator}{platform_domain}
, where {separator}
can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.
The API uses the HORISEN implementation of the OAuth 2.0 protocol. For more information, please refer to the OAuth2 Authentication Guidelines page.
2. Methods Overview
2.1 Traffic Reports
Endpoints to work with customer traffic reports.
2.2 Control Traffic Reports
Endpoints to work with control traffic reports.
3. Methods Details
3.1 Traffic Reports
Endpoints to work with customer traffic reports.
Method Overview
The method returns a list of traffic reports for a given customer invoice ID.
Authorization privilege needed for this endpoint: bulk-traffic-report.view.
Optional - privilege used for this endpoint: bulk-traffic-report-own.view.
This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.
Parameters
Name | Type | Description |
---|---|---|
invoiceId (required) | integer (path) | Invoice ID. |
operator(fieldName) | string (query) | Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: customerId, billingAccountId, billingAccountName, countryId, countryName, countryCode2, operatorId, operatorName, sellPrice, sellPriceSinceDt, sellCurrency, sellCurrencyCode, mcc, mnc.
|
Responses
Code | Description | Link |
---|---|---|
200 | List of traffic reports. | No links. |
Default | Unexpected error. | No links. |
Success Response 200: List of Traffic Reports
{
"data": [
{
"customerId": 0,
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"inSmsCnt": 0,
"sellPrice": 0,
"sellPriceSinceDt": "2023-02-23T13:39:35.427Z",
"sellCurrency": 0,
"sellCurrencyCode": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2023-02-23T13:39:35.427Z",
"endDt": "2023-02-23T13:39:35.427Z",
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
Method Overview
The method returns a list of customer traffic reports or CSV file with customer traffic reports. It generates billing reports for customers, with information associated with charges, payments, and balances.
Authorization privilege needed for this endpoint: bulk-traffic-report.view.
Optional - privilege used for this endpoint: bulk-traffic-report-own.view.
This endpoint accepts query parameters for filtering traffic reports described on URL Filtering Guidelines page.
Parameters
Name | Type | Description |
---|---|---|
startDate (required) | string($date) (query) | Start date. |
endDate (required) | string($date) (query) | End date. |
outputFormat | string (query) | Output format. Available values: json, csv. Default value: json. |
operator(fieldName) | string (query) | Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: customerId, customerBriefName, customerExtRefId, billingAccountId, billingAccountName, countryId, countryName, operatorId, operatorName.
|
Responses
Code | Description | Link |
---|---|---|
200 | List of customer traffic reports or CSV file, depending on outputFormat parameter. If the response is a CSV file, it will contain the following columns: CUSTOMER_ID, CUSTOMER_NAME, CUSTOMER_REF_ID, PRICING_COND_ID, PRICING_COND_NAME, COUNTRY, OPERATOR, MCC, MNC, PRICE_PERIOD, SMS_COUNT, CURRENCY, PRICE, AMOUNT. |
No links. |
Default | Unexpected error. | No links. |
Success Response 200: List of customer traffic reports or CSV file with customer traffic reports
{
"data": [
{
"customerId": 0,
"customerBriefName": "string",
"customerExtRefId": "string",
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2024-09-16T11:59:45.520Z",
"endDt": "2024-09-16T11:59:45.520Z",
"inSmsCnt": 0,
"sellCurrency": 0,
"sellCurrencyCode": "string",
"sellPrice": 0,
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
3.2 Control Traffic Reports
Endpoints to work with control traffic reports.
Method Overview
The method returns a list of control traffic reports for a given control invoice ID.
Authorization privilege needed for this endpoint: bulk-traffic-report.view.
Optional - privilege used for this endpoint: bulk-traffic-report-own.view.
This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.
Parameters
Name | Type | Description |
---|---|---|
invoiceId (required) | integer (path) | Invoice ID. |
operator(fieldName) | string (query) | Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: supplierId, billingAccountId, billingAccountName, countryId, countryName, countryCode2, operatorId, operatorName, buyPrice, buyPriceSinceDt, buyCurrency, buyCurrencyCode, mcc, mnc.
|
Responses
Code | Description | Link |
---|---|---|
200 | List of control traffic reports. | No links. |
Default | Unexpected error. | No links. |
Success Response 200: List of control traffic reports
{
"data": [
{
"supplierId": 0,
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"outSmsCnt": 0,
"buyPrice": 0,
"buyPriceSinceDt": "2023-02-23T13:39:35.437Z",
"buyCurrency": 0,
"buyCurrencyCode": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2023-02-23T13:39:35.437Z",
"endDt": "2023-02-23T13:39:35.437Z",
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
Method Overview
The method returns a list of control traffic reports or CSV file with control traffic reports. It generates billing reports for suppliers, with information associated with charges, payments, and balances.
Authorization privilege needed for this endpoint: bulk-traffic-report.view.
Optional - privilege used for this endpoint: bulk-traffic-report-own.view.
This endpoint accepts query parameters for filtering control traffic reports described on URL Filtering Guidelines page.
Parameters
Name | Type | Description |
---|---|---|
startDate (required) | string($date) (query) | Start date. |
endDate (required) | string($date) (query) | End date. |
outputFormat | string (query) | Output format. Available values: json, csv. Default value: json. |
operator(fieldName) | string (query) | Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: supplierId, supplierBriefName, supplierExtRefId, billingAccountId, billingAccountName, countryId, countryName, operatorId, operatorName.
|
Responses
Code | Description | Link |
---|---|---|
200 | List of control traffic reports or CSV file, depending on outputFormat parameter. If the response is a CSV file, it will contain the following columns: SUPPLIER_ID, SUPPLIER_NAME, SUPPLIER_REF_ID, PRICING_COND_ID, PRICING_COND_NAME, COUNTRY, OPERATOR, MCC, MNC, PRICE_PERIOD, SMS_COUNT, CURRENCY, PRICE, AMOUNT |
No links. |
Default | Unexpected error. | No links. |
Success Response 200: List of control traffic reports or CSV file with control traffic reports
{
"data": [
{
"supplierId": 0,
"supplierBriefName": "string",
"supplierExtRefId": "string",
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2024-09-16T12:12:42.480Z",
"endDt": "2024-09-16T12:12:42.480Z",
"outSmsCnt": 0,
"buyCurrency": 0,
"buyCurrencyCode": "string",
"buyPrice": 0,
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
Error Response Unexpected Error: Default
{
"Code": 0,
"Message": "string"
}
4. Data Models
Data Models define the structure of a JSON document and describe the data related to the Traffic Report API. It contains data for the Billing Account, Country, Operator, Prices, etc.
4.1 TrafficReportCollection
TrafficReportCollection object properties:
Name | Type | Description |
---|---|---|
data (required) | array | Array of TrafficReport objects. |
meta (required) | object | CollectionMeta object |
4.2 TrafficReport
TrafficReport object properties:
Name | Type | Description |
---|---|---|
customerId | integer | Customer ID. |
billingAccountId | integer | ID of Pricing Conditions Template. |
billingAccountName | string | Name of Pricing Conditions Template. |
countryId | integer | Country ID. |
countryName | string | Name of the Country. |
countryCode2 | string | Country code. |
operatorId | integer | Operator ID. |
operatorName | string | Operator name. |
inSmsCnt | integer | Quantity per unit. |
sellPrice | number($float) | Price per unit. |
sellPriceSinceDt | string($date-time) | Selling price from a given date. |
sellCurrency | integer | ID of selling price currency. |
sellCurrencyCode | string | SellCurrency code. |
mcc | string | Mobile country code. |
mnc | string | Mobile network code. |
startDt | string($date-time) | Start date. |
endDt | string($date‑time) | End date. |
totalAmount | number($float) | TotalAmount is price per unit multiplied by quantity per unit (totalAmount = sellPrice * inSmsCnt). |
JSON Example
{
"data": [
{
"customerId": 0,
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"inSmsCnt": 0,
"sellPrice": 0,
"sellPriceSinceDt": "2023-02-23T13:39:35.427Z",
"sellCurrency": 0,
"sellCurrencyCode": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2023-02-23T13:39:35.427Z",
"endDt": "2023-02-23T13:39:35.427Z",
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
4.3 CustTrafficReportCollection
CustTrafficReportCollection object properties:
Name | Type | Description |
---|---|---|
data (required) | array | Array of CustTrafficReport objects. |
meta (required) | object | CollectionMeta object |
4.4 CustTrafficReport
CustTrafficReport object properties:
Name | Type | Description |
---|---|---|
customerId | integer | Customer ID. |
customerBriefName | string | Customer brief name. |
customerExtRefId | string | Customer external referent ID. |
billingAccountId | integer | ID of Pricing Condition. |
billingAccountName | string | Name of Pricing Condition. |
countryId | integer | Country ID. |
countryName | string | Country name. |
countryCode2 | string | Country code. |
operatorId | integer | Operator ID. |
operatorName | string | Operator name. |
mcc | string | Mobile country code. |
mnc | string | Mobile network code. |
startDt | string($date-time) | Start date. |
endDt | string($date‑time) | End date. |
inSmsCnt | integer | Quantity per unit. |
sellCurrency | integer | ID of selling price currency. |
sellCurrencyCode | string | Selling price currency code. |
sellPrice | number($float) | Price per unit. |
totalAmount | number($float) | totalAmount is price per unit multiplied by quantity per unit (totalAmount = sellPrice * inSmsCnt). |
JSON Example
{
"data": [
{
"customerId": 0,
"customerBriefName": "string",
"customerExtRefId": "string",
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2024-09-16T11:59:45.520Z",
"endDt": "2024-09-16T11:59:45.520Z",
"inSmsCnt": 0,
"sellCurrency": 0,
"sellCurrencyCode": "string",
"sellPrice": 0,
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
4.5 ContTrafficReportCollection
ContTrafficReportCollection object properties:
Name | Type | Description |
---|---|---|
data (required) | array | Array of ContTrafficReport objects. |
meta (required) | object | CollectionMeta object |
4.6 ContTrafficReport
ContTrafficReport object properties:
Name | Type | Description |
---|---|---|
supplierId | integer | Supplier ID. |
supplierBriefName | string | Supplier brief name. |
supplierExtRefId | string | Supplier external referent ID. |
billingAccountId | integer | ID of Pricing Condition. |
billingAccountName | string | Name of Pricing Condition. |
countryId | integer | Country ID. |
countryName | string | Country name. |
countryCode2 | string | Country code. |
operatorId | integer | Operator ID. |
operatorName | string | Operator name. |
mcc | string | Mobile country code. |
mnc | string | Mobile network code. |
startDt | string($date-time) | Start date. |
endDt | string($date‑time) | End date. |
outSmsCnt | integer | Quantity per unit. |
buyCurrency | integer | ID of buying price currency. |
buyCurrencyCode | string | Buying price currency code. |
buyPrice | number($float) | Price per unit. |
totalAmount | number($float) | totalAmount is price per unit multiplied by quantity per unit (totalAmount = sellPrice * outSmsCnt). |
JSON Example
{
"data": [
{
"supplierId": 0,
"supplierBriefName": "string",
"supplierExtRefId": "string",
"billingAccountId": 0,
"billingAccountName": "string",
"countryId": 0,
"countryName": "string",
"countryCode2": "string",
"operatorId": 0,
"operatorName": "string",
"mcc": "string",
"mnc": "string",
"startDt": "2024-09-16T13:06:21.442Z",
"endDt": "2024-09-16T13:06:21.442Z",
"outSmsCnt": 0,
"buyCurrency": 0,
"buyCurrencyCode": "string",
"buyPrice": 0,
"totalAmount": 0
}
],
"meta": {
"pagination": {
"total": 0,
"count": 0,
"per_page": 0,
"current_page": 0,
"total_pages": 0,
"links": {
"first": "string",
"last": "string",
"prev": "string",
"next": "string"
}
}
}
}
4.7 Error
Name | Type | Description |
---|---|---|
code (required) | integer($int32) | Error code. |
message (required) | string | Error message. |
JSON Example
{
"Code": 0,
"Message": "string"
}
Error list
Response code | Response body | Message |
---|---|---|
401 | NOT_AUTHORIZED | Not authorized. |
500 | INT_APP_ERROR | BULK_GATE instance not found. |
500 | INT_APP_ERROR | Internal server error. |
400 | REQUEST_ERROR | Query parameter: 'propertyName' error: 'error message'. |
404 | BULK_TRAFFIC_REPORT_API_V2:BULK_RATES_SETTINGS_NOTFOUND | Bulk rates settings not found. |
4.8 CollectionMeta
CollectionMeta object properties:
Name | Type | Description |
---|---|---|
pagination | object | CollectionMetaPagination object |
4.9 CollectionMetaPagination
CollectionMetaPagination object properties:
Name | Type | Description |
---|---|---|
total (required) | integer | Total number of rows. |
count (required) | integer | A number of rows in the current page. |
per_page (required) | integer | The maximum rows per page. |
current_page (required) | integer | The current page number. |
total_pages (required) | integer | Total number of pages. |
links (required) | object | CollectionMetaPaginationLinks object |
4.10 CollectionMetaPaginationLinks
CollectionMetaPaginationLinks object properties:
Name | Type | Description |
---|---|---|
first | string | Link to the first page. |
last | string | Link to the last page. |
prev | string | Link to the previous page. |
next | string | Link to the next page. |