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.

GET/customer-invoices/{invoiceId}/traffic-reports
Returns a list of traffic reports for a given customer invoice ID.Read More
GET/customer-traffic-reports
Returns a list of customer traffic reports or CSV file with customer traffic reports.Read More

2.2 Control Traffic Reports

Endpoints to work with control traffic reports.

GET/control-invoices/{invoiceId}/traffic-reports
Returns a list of control traffic reports for a given control invoice ID.Read More
GET/control-traffic-reports
Returns a list of control traffic reports or CSV file with control traffic reports.Read More

3. Methods Details

3.1 Traffic Reports

Endpoints to work with customer traffic reports.

GET/customer-invoices/{invoiceId}/traffic-reports
Returns a list of traffic reports for a given customer invoice ID.Up
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.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case it will be treated as operator is eq (E.g. fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, a field value will be used in general search across multiple attributes.
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"
}
GET/customer-traffic-reports
Returns a list of customer traffic reports or CSV file with customer traffic reports.Up
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.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case it will be treated as operator is eq (E.g. fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, a field value will be used in general search across multiple attributes.
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.

GET/control-invoices/{invoiceId}/traffic-reports
Returns a list of control traffic reports for a given control invoice ID.Up
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.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case it will be treated as operator is eq (E.g. fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, a field value will be used in general search across multiple attributes.
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"
}
GET/control-traffic-reports
Returns a list of control traffic reports or CSV file with control traffic reports.Up
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.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case it will be treated as operator is eq (E.g. fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, a field value will be used in general search across multiple attributes.
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

Error object properties:

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.