SMS MO Inbound Filtering API

1. Introduction

The HORISEN SMS MO Inbound Filter API is made up of two parts: global filtering and advanced filtering mechanism and it is designed to manage in real-time allowlist and blocklist on SS7 Proxy Platform for Forward_SMS_MO traffic.

Global filtering mechanism allows to manipulate with the following GSM MAP and TPDU parameters:

  • SMRPDA (Home service centre address GT)
  • SMRPOA (Sender MSISDN Address)
  • TPDU-DA (Destination MSISDN Address)
  • IMSI (optional)

Advanced filtering mechanism allows to create and manage multiple of rules simultaneously, where each group is unique and independent from all other groups. Such approach provides a more flexible ability to filter incoming traffic.

Advanced filtering mechanism allows to manipulate with the following GSM MAP and TPDU parameters:

  • SMRPOA_AND_TPDUDA (Sender MSISDN Address and Destination MSISDN Address)
  • SMRPDA_AND_TPDUDA (Home service centre address GT and Destination MSISDN Address)

Global filtering rules always have higher priority than Advanced filtering rules. In case you have overlapped rules in Global filtering and Advanced filtering groups, SS7 Proxy always will handle rules with higher priorities (in this case Global filtering rules will take a place).

Please see below a description of how to use Global filtering and Advanced filtering mechanisms.

This API belongs to the SS7 domain. The subject domain of an endpoint URL is:

{address}:{port}/moin-filter/v1

2. Methods Overview

2.1 SMS-MO Inbound Filter Rule

Endpoints for SMS-MO-IN Filter Rules.

GET/rules
Gets a list of SMS-MO-IN Filter Rules.Read More
GET/rules/{id}
Gets SMS-MO-IN Filter Rule by ID.Read More

2.2 SMS-MO Inbound Filter Rule Values

Endpoints for SMS-MO-IN Filter Rule values.

POST/rule-values
Creates a new SMS-MO-IN Filter Rule values.Read More
GET/rule-values
Gets a list of SMS-MO-IN Filter Rule values.Read More
GET/rule-values/{id}
Gets SMS-MO-IN Filter Rule values by ID.Read More
PUT/rule-values/{id}
Updates SMS-MO-IN Filter Rule values by ID.Read More
DELETE/rule-values/{id}
Deletes SMS-MO-IN Filter Rule values by ID.Read More

3. Methods Details

3.1 SMS-MO Inbound Filter Rule

Endpoints for SMS-MO-IN Filter Rules.

GET/rules
Gets a list of SMS-MO-IN Filter Rules.Up
Method Overview

The method retrieves a list of SMS-MO-IN Filter Rules.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
Responses
Code Description Links
200 List of SMS-MO-IN Filter Rules is successfully retrieved. No links.
404 List of Rule is not found. No links.
Success Response 200: List of SMS-MO-IN Filter Rules

Please see below the list of available rules on SS7 Proxy Platform which includes global filtering rules and advanced filtering rules.

[
  {
    "id": 1,
    "name": "SMRPDA",
    "type": "byprefix"
  }
  {
    "id": 2,
    "name": "SMRPOA",
    "type": "byprefix"
  }
  {
    "id": 3,
    "name": "TPDUDA",
    "type": "byprefix"
  }
  {
    "id": 4,
    "name": "IMSI",
    "type": "byprefix"
  }
  {
    "id": 5,
    "name": "SMRPOA_AND_TPDUDA",
    "type": "complex"
  }
  {
    "id": 6,
    "name": "SMRPDA_AND_TPDUDA",
    "type": "complex"
  }
]
Error Response 404: Resource not found
GET/rules/{id}
Gets SMS-MO-IN Filter Rule by ID.Up
Method Overview

The method retrieves SMS-MO Inbound Filter Rule details by the given ID.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
id (required) integer($int64) (path) The ID of SMS-MO-IN Rule.
Responses
Code Description Links
200 Successful operation. No links.
404 Rule is not found. No links.
Success Response 200: SMS-MO-IN Filter Rule data
{
  "id": 1,
  "name": "SMRPDA",
  "type": "byprefix"
}
Error Response 404: Resource not found

3.2 SMS-MO Inbound Filter Rule Values

Endpoints for SMS-MO-IN Filter Rule values.

POST/rule-values
Creates a new SMS-MO-IN Filter Rule values.Up
Method Overview

The method creates SMS-MO-IN Filter Rule values.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
rule values (required) object (body) SMS-MO-IN Filter Rule values data object. Find below MOINFilterRuleValue data model description.
Data Parameters

Post data object examples of how to use global filter and advanced filter groups.

Global filter group:

Example of how to set one value for selected parameter 'SMRPOA' inside of global filter group.

We want to create a new allowlist by using the global filter mechanism for SMRPOA group.

From the list of SMS-MO-IN Filter Rules, we must select rule with id==2, in the field of value we must specify which SMRPOA must be allowed. It means that all Forward_SMS_MO messages with other values of SMRPOA will be blocked. Please see the example below.

Post data object example for global filtering mechanism with allowlist:

{
  "id": 1,
  "rule_id": 2,
  "value": "319706",
  "allow": true
}

Advanced filter group:

Example of how to set multiple values for two parameters 'SMRPOA_AND_TPDUDA' inside of advanced filter group, where values for the first and second parameters SMRPOA, TPDUDA are listed by using comma separator (,) and parameter SMRPOA and TPDUDA are separated by a semicolon (;).

We want to create a new blocklist by using advanced filter mechanism for SMRPOA_AND_TPDUDA group:

From the list of SMS-MO-IN Filter Rules, we must select rule with id==5, in the field of value we must specify the list of SMRPOA and TPDUDA separated by semicolon what must be blocked. It means that all Forward_SMS_MO messages with other values of 'SMRPOA and TPDUDA' will be allowed. Please see the example below.

Post data object example for advanced filtering mechanism with blocklist:

{
  "id": 2,
  "rule_id": 5,
  "value": "3890000000, 3790000, 36900000; 249871, 249982, 249093",
  "allow": false
}
Responses
Code Description Links
200 SMS-MO-IN Filter Rule values is created successfully. No links.
default Unexpected Error. No links.
Success Response 200: SMS-MO-IN Filter Rule values created successfully
{
  "id": 1,
  "rule_id": 2,
  "value": "319706",
  "allow": true
}
{
  "id": 2,
  "rule_id": 6,
  "value": "3890000000, 3790000, 36900000; 249871, 249982, 249093",
  "allow": false
}
Error Response Unexpected Error: Default
{
  "Code": "string",
  "Message": "string"
}
GET/rule-values
Gets a list of SMS-MO-IN Filter Rule values.Up
Method Overview

The method retrieves a list of SMS-MO-IN Filter Rule values.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
Responses
Code Description Links
200 A list of SMS-MO-IN Filter Rule values is successfully retrieved. No links.
Success Response 200: List of SMS-MO-IN Filter Rule values successfully retrieved
[
  {
    "id": 1,
    "rule_id": 1,
    "value": "319706",
    "allow": true
  }
]
[
  {
    "id": 2,
    "rule_id": 6,
    "value": "319706, 318705 ; 345120, 344124",
    "allow": false
  }
]
GET/rule-values/{id}
Gets SMS-MO-IN Filter Rule values by ID.Up
Method Overview

The method retrieves SMS-MO-IN Filter Rule values details by the given ID.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
id (required) integer($int64) (path) The ID of the rule values.
Responses
Code Description Links
200 SMS-MO-IN Filter Rule values data is successfully retrieved. No links.
404 Rule values is not found. No links.
Success Response 200: SMS-MO-IN Filter Rule values data successfully retrieved
{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": false
}
Error Response 404: Resource not found
PUT/rule-values/{id}
Updates SMS-MO-IN Filter Rule values by ID.Up
Method Overview

The method updates SMS-MO-IN Filter Rule values by the given ID.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
id (required) integer($int64) (path) The ID of the rule values to be updated.
rule values (required) object (body) Updated SMS-MO-IN Filter Rule values data object. Find below MOINFilterRuleValue data model description.
Data Parameters

Put data object example

{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": false
}
Responses
Code Description Links
200 SMS-MO-IN Filter Rule values is updated successfully. No links.
400 Invalid request data. No links.
404 SMS-MO-IN Filter Rule values is not found. No links.
Success Response 200: SMS-MO-IN Filter Rule values updated successfully
{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": false
}
Error Response 400: Invalid request
Error Response 404: Resource not found
DELETE/rule-values/{id}
Deletes SMS-MO-IN Filter Rule values by ID.Up
Method Overview

The method deletes SMS-MO-IN Filter Rule values by the given ID.

URL Parameters
Name Type Description
X-API-Key (required) string (header) The API key for authentication. Default value: 1111 or 2222.
id (required) integer($int64) (path) The ID of the rule values to be deleted.
Responses
Code Description Links
200 SMS-MO-IN Filter Rule values is deleted successfully. No links.
404 SMS-MO-IN Filter Rule values is not found. No links.
Success Response 200: SMS-MO-IN Filter Rule values deleted successfully
Error Response 404: Resource not found

4. Data Models

Data Models define the structure of a JSON document.

4.1 MOINFilterRule

MOINFilterRule object properties:

Name Type Description
id integer SMS-MO-IN Rule ID.
name string SMS-MO-IN Rule name parameters.

There are 6 parameters:

Global parameters (4 parameters):

  • SMRPDA (Service center address DA. The address SMSC GT in SIM/eSIM card for SMS Mobile)
  • SMRPOA (is original number MSISDN)
  • TPDU-DA (Destination Address)
  • IMSI

Advanced filtering mechanism (2 parameters):

  • SMRPOA_AND_TPDUDA (Sender MSISDN Address and Destination MSISDN Address)
  • SMRPDA_AND_TPDUDA (Home service center address GT and Destination MSISDN Address)
type string Specifies the matching criteria for filtering SS7 messages. Possible matching values: equal, byprefix, complex, regex.

Global filter mechanism by default is used "byprefix" type.

Advanced Filtering Mechanism is used by default - "complex" type.
JSON Examples
{
  "id": 1,
  "name": "SMRPDA",
  "type": "byprefix"
}
{
  "id": 6,
  "name": "SMRPDA_AND_TPDUDA",
  "type": "complex"
}

4.2 MOINFilterRuleValue

MOINFilterRuleValue object properties:

Name Type Description
id integer SMS-MO-IN Rule values ID.
rule_id string SMS-MO-IN Rule ID.
value string SMS-MO-IN Rule value. Any numeric value for SMRPDA, SMRPOA, TPDUDA, IMSI, SMRPOA_AND_TPDUDA, SMRPDA_AND_TPDUDA.
allow boolean Indicates if the SS7 message should be allowed or blocked. There are two allowed values: 'True' or 'False'.

'True' - allow

'False' - block
JSON Examples
{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": true
}
{
  "id": 1,
  "rule_id": 1,
  "value": "319706, 318705 ; 345120, 344124",
  "allow": false
}

4.3 Error

Error object properties:

Name Type Description
code (required) string Error code. This field sets the default value to 34 when the value is in the blocklist. There is another code - 0, it is used in the allowed list. But for all parameters the default is 34.
message (required) string Error message.
JSON Example
{
  "Code": "string",
  "Message": "string"
}

5. API Call Examples

This section presents a set of sample cURL API calls that shows some of use cases for the API.

1. An example of how to get a list of Filter Rules:

curl -H "X-API-Key: 1111" -X GET {address}:{port}/moin-filter/v1/rules

2. An example of how to get a list of Filter Rules values:

curl -H "X-API-Key: 1111" -X GET {address}:{port}/moin-filter/v1/rule-values

3. An example of how to get a Filter Rule values with given ID:

curl -H "X-API-Key: 1111" -X GET {address}:{port}/moin-filter/v1/rule-values/1

4. An example of how to post a new Filter Rule values:

curl -H "X-API-Key: 1111" -X POST -H "Content-Type: application/json" -d 
'{
  "rule_id": 1,
  "value": "31793",
  "allow": true
  }' {address}:{port}/moin-filter/v1/rule-values

5. An example of how to update a Filter Rule values with given ID:

curl -H "X-API-Key: 1111" -X PUT -H "Content-Type: application/json" -d 
'{
  "rule_id": 2,
  "value": "319703",
  "allow": false
  }' {address}:{port}/moin-filter/v1/rule-values/1

6. An example of how to delete a Filter Rule values with given ID:

curl -H "X-API-Key: 1111" -X DELETE {address}:{port}/moin-filter/v1/rule-values/1

7. An example of how to update a Filter Rule values with given ID:

curl -H "X-API-Key: 1111" -X PUT -H "Content-Type: application/json" -d
'{
  "rule_id": 4,
  "value": "3159",
  "allow": false
  }' {address}:{port}/moin-filter/v1/rule-values/1