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)
- SMRPOA_AND_TPDUDA_AND_SCCPClgGT (Sender MSISDN Address and Destination MSISDN Address and SCCP Calling global title)
- SMRPOA_AND_TPDUDA_AND_SCCPClgGT_AND_IMSI (Sender MSISDN Address and Destination MSISDN Address and SCCP Calling global title and IMSI)
Global filtering rules have the following priority:
- blocklist basic (global filtering)
- blocklist advanced (advanced filtering)
- allowlist basic (global filtering)
- allowlist advanced (advanced filtering)
If a message does not match any rules from the blocklist, then it begins to be checked in the allow list. If it matches at least one rule from the blocklist, the message is blocked and does not go further.
Further, if the allowlist is empty, then the message goes further.
If the allowlist is not empty, then the message must match at least one rule value for each rule from the allowlist in order to proceed further. That is, if you have 5 rules for MSISDN (rule_id 2) and 7 rules for TPDUDA (rule_id 3), then the message must match at least one rule for MSISDN and one for TPDUDA.
To create filters we can use * and ? as in regular expressions. Spaces are not taken into account when checking.
"?" means the mandatory presence of one character, for example: "12?4?67" matches 1234567, 1294067 and does not match 12345678
"*" means an optional number of characters, for example: "123*" matches 123, 1234, 12345 and does not match 0123
These symbols can appear in any place (at the beginning, at the end, in the middle). If there are no characters, an exact equal comparison will be made.
You can also group values using square brackets. For example the following rule:
"123,456; 234,456; 345,456; 123,123"
may be shortened:
"[123,234,345],456; 123,123"
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/v0
2. Methods Overview
2.1 SMS-MO Inbound Filter Rule
Endpoints for SMS-MO-IN Filter Rules.
2.2 SMS-MO Inbound Filter Rule Values
Endpoints for SMS-MO-IN Filter Rule values.
3. Methods Details
3.1 SMS-MO Inbound Filter Rule
Endpoints for SMS-MO-IN Filter Rules.
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",
"error_code": "34"
}
{
"id": 2,
"name": "SMRPOA",
"type": "byprefix",
"error_code": "34"
}
{
"id": 3,
"name": "TPDUDA",
"type": "byprefix",
"error_code": "34"
}
{
"id": 4,
"name": "IMSI",
"type": "byprefix",
"error_code": "34"
}
{
"id": 5,
"name": "SMRPOA_AND_TPDUDA",
"type": "complex",
"error_code": "34"
}
{
"id": 6,
"name": "SMRPDA_AND_TPDUDA",
"type": "complex",
"error_code": "34"
}
{
"id": 7,
"name": "SMRPOA_AND_TPDUDA_AND_SCCPClgGT",
"type": "complex",
"error_code": "34"
}
{
"id": 8,
"name": "SMRPOA_AND_TPDUDA_AND_SCCPClgGT_AND_IMSI",
"type": "complex",
"error_code": "34"
}
]
Error Response 404: Resource not found
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_code": "34"
}
Error Response 404: Resource not found
3.2 SMS-MO Inbound Filter Rule Values
Endpoints for SMS-MO-IN Filter Rule values.
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 the groups 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, 249871; 3790000, 249982; 36900000, 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, 249871; 3790000, 249982; 36900000, 249093",
"allow": false
}
Error Response Unexpected Error: Default
{
"Code": "string",
"Message": "string"
}
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, 345120; 318705, 344124",
"allow": false
}
]
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
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
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 8 parameters: Global parameters (4 parameters):
Advanced filtering mechanism (4 parameters):
|
type | string | Specifies the matching criteria for filtering SS7 messages. Possible matching values: byprefix, complex. 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",
"error_code": "34"
}
{
"id": 6,
"name": "SMRPDA_AND_TPDUDA",
"type": "complex",
"error_code": "34"
}
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, SMRPOA_AND_TPDUDA_AND_SCCPClgGT, SMRPOA_AND_TPDUDA_AND_SCCPClgGT_AND_IMSI. |
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": 2,
"rule_id": 6,
"value": "319706, 345120; 318705, 344124",
"allow": false
}
4.3 Error
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/v0/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/v0/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/v0/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/v0/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/v0/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/v0/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/v0/rule-values/1