Test System API

1. Introduction

HORISEN Test System API is used for testing the traffic performance of SMS routes in real-time.

With HORISEN Test System API, SMS routes are tested by running SMS tests. With detailed testing results, it measures delivery, availability and perform text message content check.
Test detects failures and routes with fake DLR. It confirms that the text message content is displayed correctly, and which SMSC was used for the SMS delivery.

The subject domain of an endpoint URL is:

https://api.horisen.pro/gate/testsystem/v1

HORISEN Test System API is REST API with OAuth 2.0 Password Grant type.
The Password grant type is a way to exchange a user's credentials for an access token. The token expires in 3600 seconds, after that requires to login again.

2. Methods Overview

2.1 Test SMS

2.2 Test SMS Language

2.3 Test Operator

2.4 Test Operator Country

2.5 Test Route

2.6 Test Route Category

2.7 Test Route Supplier

2.8 Test Route Gate

3. Methods Details

3.1 Test SMS

Method Overview

The method adds a TestSms. An SMS is sent to test gate routes.

Parameters

Name	Type	Description
post data (required)	object (body)	Data to send test sms.

Data Parameters

Name	Type	Description
username (required)	string	The username.
test (required)	string	The name of a test.
gate_id (required)	array	An array of gate IDs.
mcc (optional)	array	An array of Mobile Country Codes.
mcc_mnc (optional)	array	An array of MCC_MNCs, Mobile Country Code and Mobile Number Code.
operator_owner (optional)	string	Possible values: 'platform', 'me'. Default value: 'platform'.
sender (optional)	string	The name of a sender.
sender_random (optional)	string	It can be 'alpha', 'numeric', 'short' type.
sender_same (optional)	string	If the sender is same for multitest. It can be 'alpha', 'numeric', 'short' type.
text_lang (required)	string	Example: 'en', 'de', 'fr', 'it', 'es', 'zx', ...
text_type (required)	string	Possible values: 'gsm', 'gsm_concat', 'gsm_set', 'ucs', 'ucs_concat', 'ucs_set'.
callback_api (required)	string	Example: 'https://your.domain.com/your-callbackurl'

One of 'mcc' or 'mcc_mnc' is required and must be set. If 'mcc' is set, SMS will be sent to all operators from countries.
If 'mcc_mnc' is set, 'mcc' 'will not be considered.

Using random SMS template:

• text_lang and text_type are required
• sender defined by template will be used if: 'sender', 'sender_random', 'sender_same' are omitted.

Data to send test sms object example:

{
  "username": "testsms@fb.com",
  "test": "FB API",
  "gate_id": [6],
  "mcc": [],
  "mcc_mnc": [26202],
  "operator_owner": "",
  "sender": "facebook",
  "sender_random": "",
  "sender_same": "",
  "text_lang": "en",
  "text_type": "gsm",
  "callback_api": "https://your.domain.com/your-callbackurl" 
}

Responses

Code	Description	Links
201	TestSms is added.	No links
429	Rate limit is reached.	No links
default	Unexpected Error.	No links

Success Response - 201: TestSms is added

{
  "test_session": 1539686679146599400
}

Headers

Name	Type	Description
X-Ratelimit-Limit	integer	Request limit per day.
X-Ratelimit-Remaining	integer	The number of requests left for the time window.
X-Ratelimit-Reset	integer	The number of seconds to midnight in UTC timezone at which the current rate limit window resets.

Rate Limiting Response - 429: Rate limit is reached

{
  "code": "GATE_TEST_SYSTEM:RATE_LIMIT_REACHED",
  "message": "Rate limit reached"
}

Headers:

Name	Type	Description
X-Ratelimit-Limit	integer	Request limit per day.
X-Ratelimit-Remaining	integer	The number of requests left for the time window.
X-Ratelimit-Reset	integer	The number of seconds to midnight in UTC timezone at which the current rate limit window resets.

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.2 Test SMS Language

Method Overview

The method returns a list of all languages of a Test SMS text to be sent.

Parameters

Name	Type	Description
code	string (query)	A language code.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10
q	string (query)	Search criteria. Available field: name.
sort	string (query)	Sort options in form of sort=-attribute1,attribute2,-attribute3. Sort available field: name.

Responses

Code	Description	Links
200	A list of Test SMS Languages.	No links
default	Unexpected Error.	No links

Success Response 200: List of Test SMS Languages

{
  "data": [
    {
      "name": "string",
      "code": "string"
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.3 Test Operator

Method Overview

The method returns a list of all Operators where SMS will be sent.

Parameters

Name	Type	Description
owner (required)	string (query)	Possible values: 'platform', 'me'.
mcc_mnc	integer (query)	MCC_MNC Mobile Country Code and Mobile Number Code.
mcc	string (query)	A list of MCCs comma separated (mcc1, mcc2, mcc3, ...).
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	Search criteria. Available fields: operator name, country name.
sort	string (query)	Sort options in form of sort=-attribute1,attribute2,-attribute3. Sort available fields: operator name, country name.

Responses

Code	Description	Links
200	A list of Operators	No links
default	Unexpected Error	No links

Success Response 200: List of Operators

{
  "data": [
    {
      "name": "string",
      "mcc_mnc": 0,
      "country": "string",
      "mcc": 0
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.4 Test Operator Country

Method Overview

The method returns a list of Countries of available operators where SMS can be sent.

Parameters

Name	Type	Description
owner (required)	string (path)	Possible values: 'platform', 'me'.
name	string (query)	A country name.
mcc	integer (query)	MCC - Mobile Country Code.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	Search criteria. Available field: name.
sort	string (query)	Sort options in form of sort=-attribute1,attribute2,-attribute3. Sort available field: name.

Responses

Code	Description	Links
200	A list of Operator Countries	No links
default	Unexpected Error	No links

Success Response 200: List of Operators

{
  "data": [
    {
      "name": "string",
      "mcc": "string"
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.5 Test Route

Method Overview

The method returns a list of all Routes.

Parameters

Name	Type	Description
gate_name	string (query)	A gate name.
category_name	string (query)	A category name.
supplier_name	string (query)	A supplier name.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	Search criteria. Available fields: gate_name, category_name, supplier_name.

Responses

Code	Description	Links
200	A list of Routes	No links
default	Unexpected Error	No links

Success Response 200: List of Routes

{
  "data": [
    {
      "gate_id": 0,
      "gate_name": "string",
      "category_id": 0,
      "category_name": "string",
      "supplier_id": 0,
      "supplier_name": "string",
      "param_id": 0,
      "param_name": "string",
      "param_value": "string"
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

Method Overview

The method adds a Route. The route is a gate route that is being tested.

Parameters

Name	Type	Description
post data	object (body)	Data to save test route.

Data Parameters

Name	Type	Description
category (required)	string	A route category.
supplier (required)	string	The name of a supplier.
gate (required)	string	The name of a gate.
tlv_tag (optional)	string	A type-length-value tag.
tlv_value (optional)	string	A type-length-value value.
service_type (optional)	string	A service type name.
prefix (optional)	string	A prefix.
gate_id (optional)	integer	A gate ID.

If 'tlvTag' is set, then 'tlvValue' is required.
One of 'tlvTag', 'serviceType', 'prefix', is required and must be set.

Data to save test route object example:

{
  "category": "Direct",
  "supplier": "Syniverse",
  "gate": "Mach Silver",
  "tlv_tag": "",
  "tlv_value": "",
  "service_type": "srv1",
  "prefix": "",
  "gate_id": 0
}

Responses

Code	Description	Links
201	A test route is added.	No links
default	Unexpected Error	No links

Success Response - 201: Test route is added

{
  "status": "OK"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.6 Test Route Category

Method Overview

The method returns a list of all Route Categories.

Parameters

Name	Type	Description
name	string (query)	A category name.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	Search criteria. Available field: name.
sort	string (query)	Sort options in form of sort=-attribute1,attribute2,-attribute3. Sort available field: name.

Responses

Code	Description	Links
200	A list of route categories.	No links
default	Unexpected Error.	No links

Success Response 200: List of Route Categories

{
  "data": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

Method Overview

The method deletes a Route Category for a given ID.

Parameters

Name	Type	Description
id (required)	string (path)	A route category ID.

Responses

Code	Description	Links
200	A route category deleted successfully.	No links
default	Unexpected Error.	No links

Success Response 200: List of Routes

{
  "id": "string",
  "name": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.7 Test Route Supplier

Method Overview

The method returns a list of all Route Suppliers.

Parameters

Name	Type	Description
name	string (query)	A supplier name.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	Search criteria. Available fields: gate_name, category_name, supplier_name.
sort	string (query)	Sort options in form of sort=-attribute1,attribute2,-attribute3. Sort available field: name.

Responses

Code	Description	Links
200	A list of Route Suppliers.	No links
default	Unexpected Error.	No links

Success Response 200: List of Route Suppliers

{
  "data": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

Method Overview

The method deletes a Route Supplier for a given ID.

Parameters

Name	Type	Description
id	string (path)	A route Supplier ID.

Responses

Code	Description	Links
200	A Route Supplier deleted successfully.	No links
default	Unexpected Error.	No links

Success Response 200: Route Supplier deleted

{
  "id": "string",
  "name": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

3.8 Test Route Gate

Method Overview

The method returns a list of all Route Gates.

Parameters

Name	Type	Description
name	string (query)	A gate name.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	Search criteria. Available field: name.
sort	string (query)	Sort options in form of sort=-attribute1,attribute2,-attribute3. Sort available field: name.

Responses

Code	Description	Links
200	A list of Route Gates.	No links
default	Unexpected Error.	No links

Success Response 200: List of Route Gates

{
  "data": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string"
}

Method Overview

The method deletes a Route Gate for a given ID.

Parameters

Name	Type	Description
id	string (path)	A Route Gate ID.

Responses

Code	Description	Links
200	A Route Gate deleted successfully.	No links
default	Unexpected Error.	No links

Success Response 200: Route Gate deleted

{
  "id": "string",
  "name": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string"
  "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 Test System API.

Name	Type	Description
TestSmsPostData	object	TestSmsPostData object

TestSmsPostData object properties:

Name	Type	Description
username (required)	string	The username.
test (required)	string	The name of a test.
gate_id (required)	array	An array of Gate IDs. Gate ID is integer type.
mcc (optional)	array	An array of MCCs. MCC is integer type.
mcc_mnc (optional)	array	An array of gate MCC_MNCs. MCC_MNC is integer type.
operator_owner (optional)	string	Possible values: 'platform', 'me'. Default: 'platform'.
sender (optional)	string	The name of a sender.
sender_random (optional)	string	It can be 'alpha', 'numeric', 'short'.
sender_same (optional)	string	If the sender name have changed. It can be 'alpha', 'numeric', 'short'.
text_lang (required)	string	Example: 'en', 'de', 'fr', 'it', 'es', 'zx', ...
text_type (required)	string	Possible values: 'gsm', 'gsm_concat', 'gsm_set', 'ucs', 'ucs_concat', 'ucs_set'.
callback_api (required)	string	Example: "https://your.domain.com/your-callbackurl"

JSON Example

"data": [
    {
     "username": "testsms@fb.com",
     "test": "FB API",
     "gate_id": [6],
     "mcc": [],
     "mcc_mnc": [26202],
     "sender": "fb",
     "text_lang": "en",
     "text_type": "gsm",
     "callback_api": "https://your.domain.com/your-callbackurl" 
    }
  ]

Name	Type	Description
TestSmsPostResponse	object	TestSmsPostResponse object

TestSmsPostResponse object properties:

Name	Type	Description
test_session	integer	A session number.

JSON Example

{
  "test_session": 1539686679146599400
}

Name	Type	Description
RateLimitReachedResponse	object	RateLimitReachedResponse object

RateLimitReachedResponse object properties:

Name	Type	Description
code (required)	string	A response code.
message (required)	string	A response message.

JSON Example

{
  "code": "GATE_TEST_SYSTEM:RATE_LIMIT_REACHED",
  "message": "Rate limit reached"
}

Name	Type	Description
TestRoutePostData	object	TestRoutePostData object

TestRoutePostData object properties:

Name	Type	Description
category	string	A category name.
supplier	string	A supplier name.
gate	string	a Gate name.
tlv_tag	string	A type-length-value tag.
tlv_value	string	A type-length-value value.
service_type	string	A service type name.
prefix	string	A prefix.
gate_id	integer	A gate ID.

JSON Example

{
  "category": "Direct",
  "supplier": "Syniverse",
  "gate": "Mach Silver",
  "tlv_tag": "",
  "tlv_value": "",
  "service_type": "srv1",
  "prefix": "",
  "gate_id": 0
}

Name	Type	Description
TestRoutePostResponse	object	TestRoutePostResponse object

TestRoutePostResponse object properties:

Name	Type	Description
status	string	A response status.

JSON Example

{
  "status": "OK"
}

Name	Type	Description
TestSmsLanguageCollection	object	TestSmsLanguageCollection object

TestSmsLanguageCollection object properties:

Name	Type	Description
data (required)	array	An array of TestSmsLanguage objects.
meta (required)	object	CollectionMeta object

TestSmsLanguage object properties:

Name	Type	Description
name	string	A language name.
code	string	A language code.

Name	Type	Description
OperatorCollection	object	OperatorCollection object

OperatorCollection object properties:

Name	Type	Description
data (required)	array	An array od Operator objects.
meta (required)	object	CollectionMeta object

Operator object properties:

Name	Type	Description
name	string	An operator name.
mcc_mnc	integer	MCC_MNC Mobile Country Code and Mobile Number Code.
country	string	A country name.
mcc	integer	MCC - Mobile Country Code.

Name	Type	Description
OperatorCountryCollection	object	OperatorCountryCollection object

OperatorCountryCollection object properties:

Name	Type	Description
data (required)	array	An array of OperatorCountry objects.
meta (required)	object	CollectionMeta object

OperatorCountry object properties:

Name	Type	Description
name	string	A country name.
mcc	string	MCC - Mobile Country Code.

Name	Type	Description
RouteCollection	object	RouteCollection object

RouteCollection object properties:

Name	Type	Description
data (required)	array	An array of Route objects.
meta (required)	object	CollectionMeta object

Route object properties:

Name	Type	Description
gate_id	integer	A gate ID.
gate_name	string	A gate name.
category_id	integer	A category ID.
category_name	string	A category name.
supplier_id	integer	A supplier ID.
supplier_name	string	A supplier name.
param_id	integer	A parameter ID.
param_name	string	A parameter name.
param_value	string	A parameter value.

Name	Type	Description
RouteCategoryCollection	object	RouteCategoryCollection object

RouteCategoryCollection object properties:

Name	Type	Description
data (required)	array	An array of RouteCategory objects.
meta (required)	object	CollectionMeta object

RouteCategory object properties:

Name	Type	Description
id	string	A route category ID.
name	string	A route category name.

Name	Type	Description
RouteSupplierCollection	object	RouteSupplierCollection object

RouteSupplierCollection object properties:

Name	Type	Description
data (required)	array	An array of RouteSupplier objects.
meta (required)	object	CollectionMeta object

RouteSupplier object properties:

Name	Type	Description
id	string	A route supplier ID.
name	string	A route supplier name.

Name	Type	Description
RouteGateCollection	object	RouteGateCollection object

RouteGateCollection object properties:

Name	Type	Description
data (required)	array	An array of RouteGate objects.
meta (required)	object	CollectionMeta object

RouteGate object properties:

Name	Type	Description
id	string	A route gate ID.
name	string	A route gate name.

Name	Type	Description
TestResult	object	TestResult object

TestResult object properties:

Name	Type	Description
msg_id	string	A message ID.
sent_date	datetime	The date when the message is sent.
username	string	A username.
test_id	string	A test ID.
test_session	string	A test session.
test_node	string	A test node.
supplier	string	A supplier name.
gate_category	string	A gate category.
gate	string	A gate name.
gate_id	integer	A gate ID.
country	string	A country name.
operator	string	An operator name.
operator_id	integer	An operator ID.
dcs	string	Data Coding Scheme.
concat	string	If message is concatenated.
num_parts	integer	The number of parts.
sender	string	A name of a sender.
text	string	A message text.
price	string	A price.
currency	string	A price currency.
receiver	string	A name of a receiver.
dlr_status	string	DLR status.
dlr_date	datetime	The date of DLR.
dlr_delay	string	Delay of DLR.
fake_dlr	string	If DLR is fake or not.
status	string	A sending status.
sender_match	string	If sender data is matched.
text_match	string	If sender data is matched.
encoding_match	string	If encoding is matched.
received_date	datetime	The date when the message is received.
received_sender	string	A sender that is received.
received_text	string	The text that is received.
received_dcs	string	The received DCS.
received_mcc_mnc	string	The received MCC_MNC.
received_operator	string	The received operator.
received_service_center	string	The received service center.
received_service_operator	string	The received service operator.
received_service_country	string	The received country.
received_service_pdu	string	The received service PDU.
received_service_pdu_parts	array	The received service PDU parts.
sms_delay	string	SMS delay.
direct_route	string	If a route is direct or not.
national_smsc	string	National SMSC.

JSON Example

{
  "msg_id": "39013f69-d09d-4140-bbf5-b47007465e2f",
  "sent_date": "2019-01-18T15:07:12Z",
  "username": "API",
  "test_id": "PlayaX",
  "test_session": "1547824032419106019",
  "test_node": "Platform",
  "supplier": "Syniverse",
  "gate_category": "Direct",
  "gate": "Mach",
  "gate_id": 8,
  "country": "Germany",
  "operator": "Vodafone Germany",
  "operator_id": 2347,
  "dcs": "gsm",
  "concat": "no",
  "num_parts": 1,
  "sender": "zeka",
  "text": "Dein Bizness-Prozess endete heute. Wenn du immer noch interessiert bist, gibt es hier eine 10% Rabatt auf Promo! Danke, dass du Bizness ausprobiert hast.",
  "receiver": "+491703458213",
  "dlr_status": "delivered",
  "dlr_date": "2018-11-02T14:40:50+01:00",
  "dlr_delay": "13.731 sec",
  "fake_dlr": "no",
  "status": "success",
  "sender_match": "yes",
  "text_match": "yes",
  "encoding_match": "yes",
  "received_date": "2018-11-02T14:40:38+01:00",
  "received_sender": "zeka",
  "received_text": "Dein Bizness-Prozess endete heute. Wenn du immer noch interessiert bist, gibt es hier eine 10% Rabatt auf Promo! Danke, dass du Bizness ausprobiert hast.",
  "received_dcs": "gsm",
  "received_mcc_mnc": "26201",
  "received_operator": "",
  "received_service_center": "+491722270333",
  "received_service_operator": "Vodafone Germany",
  "received_service_country": "Germany",
  "received_service_pdu": "07919471227230332407D0FAF23A0C000081112041048340A0C472DA0D12A6F5EEF27CDE82CADFFAF27C0E2ABBC9657A19842ED7E96517E85A76BB41E43A28DD6E97E520F77B8C06A5DDF4B2BC3C9FA7CB723A489C9ED359A0735A4C0795E72074BA2C0795D3EE3228062B81A46171984E0785EB661054FE6EBF416D376AAE668740C4B07B5D6681C8E1F91C44AE838469BDBB3C9F83C2F5395CFE16A7CB723A081D9ED35D",
  "received_service_pdu_parts": [],
  "sms_delay": "1.000 sec",
  "direct_route": "yes",
  "national_smsc": "yes"
}

Name	Type	Description
Error	object	Error object

Error object properties:

Name	Type	Description
code (required)	string	Error code.
message (required)	string	Error message.

JSON Example

{
  "Code": "string",
  "Message": "string"
}

4.2 Meta

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

Name	Type	Description
CollectionMeta	object	CollectionMeta object

CollectionMeta object properties:

Name	Type	Description
pagination (required)	object	Pagination object

pagination object properties:

Name	Type	Description
count (required)	integer	A number of rows in the current page.
current_page (required)	integer	The current page number.
per_page (required)	integer	The maximum rows per page.
total (required)	integer	Total number of rows.
total_pages (required)	integer	Total number of pages.

JSON Example

"meta": {
    "pagination": {
      "count": 0,
      "current_page": 0,
      "per_page": 0,
      "total": 0,
      "total_pages": 0
    }
  }