Traffic Report API v2

1. Introduction

The HORISEN Traffic Report API is used for creating traffic reports for the BULK SMS API.

This API returns information about traffic associated with an invoice with a given ID. It returns the number of sent messages, the price per message and the total amount for each pricing condition, country, operator and selling/buying price. The requests are carried out by using a GET method.

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

Endpoint for an invoice traffic reports.

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

2.2 Control Traffic Reports

Endpoint for a control invoice traffic reports.

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

3. Methods Details

3.1 Traffic Reports

Endpoint for an invoice 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"
}

3.2 Control Traffic Reports

Endpoint for a control invoice 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"
}

4. Data Models

Data Models define the structure of a JSON document.

4.1 Data

Data describe all the data related to the Traffic Reports. It contains data for the Billing Account, Country, Operator, Prices, etc.

Name Type Description
TrafficReportCollection object TrafficReportCollection object

TrafficReportCollection object properties:

Name Type Description
data (required) array Array of TrafficReport objects.
meta (required) object CollectionMeta object

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"
      }
    }
  }
}
Name Type Description
ControlTrafficReportCollection object ControlTrafficReportCollection object

ControlTrafficReportCollection object properties:

Name Type Description
data (required) array Array of ControlTrafficReport objects.
meta (required) object CollectionMeta object

ControlTrafficReport object properties:

Name Type Description
supplierId integer Supplier 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.
outSmsCnt integer Quantity per unit.
buyPrice number($float) Buying price per unit.
buyPriceSinceDt string($date-time) Buying price from a given date.
buyCurrency integer ID of buying price currency.
buyCurrencyCode string BuyCurrency 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 = buyPrice * outSmsCnt).
JSON Example
{
  "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"
      }
    }
  }
}
Name Type Description
Error object Error object

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.2 Meta

Meta contains the data for the number of rows and pages that have been received for an API call.

Name Type Description
collectionMeta object CollectionMeta object

CollectionMeta object properties:

Name Type Description
pagination object CollectionMetaPagination object

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

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.