SMS MT Inbound Filtering API

1. Introduction

The HORISEN SMS MT Inbound Filter API is designed to manage in real-time allowlist and blocklist on SS7 Proxy platform by filtering incoming SMS MT traffic from SS7 network.

Filtering is based on the following GSM MAP and TPDU parameters:

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

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

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

2. Methods Overview

2.1 SMS-MT Inbound Filter Rule

Endpoints for working with SMS-MT-IN Filter Rules.

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

2.2 SMS-MT Inbound Filter Rule Values

Endpoints for working with SMS-MT-IN Filter Rule values.

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

3. Methods Details

3.1 SMS-MT Inbound Filter Rule

Endpoints for working with SMS-MT-IN Filter Rules.

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

The method retrieves a list of SMS-MT-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-MT-IN Filter Rules successfully retrieved. No links.
404 Rule not found. No links.
Success Response 200: List of SMS-MT-IN Filter Rules
[
  {
    "id": 1,
    "name": "FSMMTReq.SMRPOA",
    "type": "byprefix"
  }
]
Error Response 404: Resource not found
GET/rules/{id}
Gets an SMS-MT-IN Filter Rule by ID.Up
Method Overview

The method retrieves an SMS-MT 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 an SMS-MT-IN Rule.
Responses
Code Description Links
200 Successful operation. No links.
404 Rule not found. No links.
Success Response 200: SMS-MT-IN Filter Rule data
{
  "id": 1,
  "name": "FSMMTReq.SMRPOA",
  "type": "byprefix"
}
Error Response 404: Resource not found

3.2 SMS-MT Inbound Filter Rule Values

Endpoints for working with SMS-MT-IN Filter Rule values.

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

The method creates an SMS-MT-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-MT-IN Filter Rule values data object. Find below MTINFilterRuleValue data model description.
Data Parameters

Post data object example

{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": false
}
Responses
Code Description Links
200 SMS-MT-IN Filter Rule values created successfully. No links.
default Unexpected Error. No links.
Success Response 200: SMS-MT-IN Filter Rule values created successfully
{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": false
}
Error Response Unexpected Error: Default
{
  "Code": "string",
  "Message": "string"
}
GET/rule-values
Gets a list of SMS-MT-IN Filter Rule values.Up
Method Overview

The method retrieves a list of SMS-MT-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-MT-IN Filter Rule values successfully retrieved. No links.
Success Response 200: List of SMS-MT-IN Filter Rule values successfully retrieved
[
  {
    "id": 1,
    "rule_id": 1,
    "value": "319706",
    "allow": false
  }
]
GET/rule-values/{id}
Gets an SMS-MT-IN Filter Rule values by ID.Up
Method Overview

The method retrieves an SMS-MT-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-MT-IN Filter Rule values data successfully retrieved. No links.
404 Rule values not found. No links.
Success Response 200: SMS-MT-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 an SMS-MT-IN Filter Rule values by ID.Up
Method Overview

The method updates an SMS-MT-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-MT-IN Filter Rule values data object.
Data Parameters

Put data object example

{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "allow": false
}
Responses
Code Description Links
200 SMS-MT-IN Filter Rule values updated successfully. No links.
400 Invalid request data. No links.
404 SMS-MT-IN Filter Rule values not found. No links.
Success Response 200: SMS-MT-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 an SMS-MT-IN Filter Rule values by ID.Up
Method Overview

The method deletes an SMS-MT-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-MT-IN Filter Rule values deleted successfully. No links.
404 SMS-MT-IN Filter Rule values not found. No links.
Success Response 200: SMS-MT-IN Filter Rule values deleted successfully
Error Response 404: Resource not found

4. Data Models

Data Models define the structure of a JSON document and describe the data related to the SMS MT Inbound Filtering API.

4.1 MTINFilterRule

MTINFilterRule object properties:

Name Type Description
id integer SMS-MT-IN Rule ID.
name string SMS-MT-IN Rule name parameters.
There are four parametrs:
  • SRISMReq.MSISDNRanges,
  • FSMMTReq.SMRPOA,
  • FSMMTReq.SMRPDA,
  • SRISMReq.SCAddressGT.
For each parameter, the 'byprefix' type is used.
type string Specifies the matching criteria for filtering SS7 messages. Possible values: equal, byprefix, regex. By default 'byprefix' is used.
JSON Example
{
  "id": ,
  "name": "FSMMTReq.SMRPOA",
  "type": "byprefix"
}

4.2 MTINFilterRuleValue

MTINFilterRuleValue object properties:

Name Type Description
id integer SMS-MT-IN Rule values ID.
rule_id string SMS-MT-IN Rule ID.
value string SMS-MT-IN Rule value. Any numeric value, for example for FSMMTReq.SMRPOA.
allow boolean Indicates if the SS7 message should be allowed to continue its normal flow within the network. 'True' or 'false' is used, where 'true' is allowed for the set value of a certain parameter, 'false' is a blocklist.
JSON Example
{
  "id": 1,
  "rule_id": 1,
  "value": "319706",
  "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 is given below:

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

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

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

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

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

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

curl -H "X-API-Key: 1111" -X POST -H "Content-Type: application/json" -d 
'{
  "rule_id": 1,
  "value": "FSMMTReq.SMRPOA",
  "allow": false
  }' {address}:{port}/mtin-filter/v1/rule-values

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

curl -H "X-API-Key: 1111" -X PUT -H "Content-Type: application/json" -d
'{
  "rule_id": 1,
  "value": "FSMMTReq.SMRPOA",
  "allow": true
  }' {address}:{port}/mtin-filter/v1/rule-values/1

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

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