SMSC API – JSON API for YateSMSC Control

Yate-based Short Message Service Center has the functions of receiving, forwarding, storing and delivering SMSs in GSM, UMTS, LTE or custom networks. This page is presenting the SMSC JSON API requests and responses for YateSMSC control.

Request: query_stats

Retrieve statistics from a running node.

Request: query_messages

Retrieve waiting messages counters for a subscriber.
The subscriber should be identified by MSISDN since this is the primary identity for a SMSC.
Identification by IMSI works only for own subscribers and not even always.

Requests

This request has multiple formats in which it can be sent:

{
    "request": "query_messages",
    "node": "smsc",
    "params": {
        "msisdn": "Mandatory, string. Phone number of the subscriber.",
        "details": "Optional, bool, default=false. Retrieve mode details about the subscriber."
    }
}
{
    "request": "query_messages",
    "node": "smsc",
    "params": {
        "imsi": "Mandatory, string. International Mobile Subscriber Identity",
        "details": "Optional, bool, default=false. Retrieve mode details about the subscriber."
    }
}

Response

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "waiting": {
        "imsi": "International Mobile Subscriber Identity",
        "sending": {
            "destinations": "Distinct destinations waiting for delivery",
            "messages": "Total number of MO-SMS waiting in SMSC",
            "list": [
                {
                    "id": "Unique numeric message ID",
                    "ref": "TP-MR reference if available",
                    "billid": "Billing ID",
                    "retries": "Number of retries left",
                    "destination": "MSISDN of destination",
                    "submit_info": "Protocol and address used to insert message in SMSC",
                    "last_error": "Text of last delivery attempt error"
                }
            ]
        },
        "receiving": {
            "originators": "Distinct originators for waiting messages",
            "messages": "Total number of MT-SMS waiting in SMSC",
            "list": [
                {
                    "id": "Unique numeric message ID",
                    "ref": "TP-MR reference if available",
                    "billid": "Billing ID",
                    "retries": "Number of retries left",
                    "originator": "MSISDN or name of sender",
                    "submit_info": "Protocol and address used to insert message in SMSC",
                    "last_error": "Text of last delivery attempt error"
                }
            ]
        }
    }
}
{
    "code": 0,
    "waiting": {
        "msisdn": "hone number of the subscriber.",
        "sending": {
            "destinations": "Distinct destinations waiting for delivery",
            "messages": "Total number of MO-SMS waiting in SMSC",
            "list": [
                {
                    "id": "Unique numeric message ID",
                    "ref": "TP-MR reference if available",
                    "billid": "Billing ID",
                    "retries": "Number of retries left",
                    "destination": "MSISDN of destination",
                    "submit_info": "Protocol and address used to insert message in SMSC",
                    "last_error": "Text of last delivery attempt error"
                }
            ]
        },
        "receiving": {
            "originators": "Distinct originators for waiting messages",
            "messages": "Total number of MT-SMS waiting in SMSC",
            "list": [
                {
                    "id": "Unique numeric message ID",
                    "ref": "TP-MR reference if available",
                    "billid": "Billing ID",
                    "retries": "Number of retries left",
                    "originator": "MSISDN or name of sender",
                    "submit_info": "Protocol and address used to insert message in SMSC",
                    "last_error": "Text of last delivery attempt error"
                }
            ]
        }
    }
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}
{
    "code": 402,
    "message": "Missing both 'msisdn' and 'imsi' parameters."
}
{
    "code": 404,
    "message": "IMSI not found"
}
{
    "code": 404,
    "message": "MSISDN not found"
}
{
    "code": 502,
    "message": "Database error."
}

Examples: query_messages

Orange Dot SMSC API - JSON API for YateSMSC Control

Retrieve waiting messages counters for MSISDN ‘96388270078’. Short Response.

Request

{
    "request": "query_messages",
    "node": "smsc",
    "params": {
        "msisdn": "96388270078"
    }
}

Response

{
    "code": 0,
    "waiting": {
        "imsi": "001019901001078",
        "receiving": {
            "originators": 1,
            "messages": 1
        }
    }
}
Orange Dot SMSC API - JSON API for YateSMSC Control

Retrieve waiting messages counters for MSISDN ‘96388270078’. Detailed Response.

Request

{
    "request": "query_messages",
    "node": "smsc",
    "params": {
        "msisdn": "96388270078",
        "details": true
    }
}

Response

{
    "code": 0,
    "waiting": {
        "imsi": "001019901001078",
        "receiving": {
            "originators": 1,
            "messages": 1,
            "list": [
                {
                    "id": 110801,
                    "retries": 2,
                    "billid": "1581090613-4",
                    "originator": "345678",
                    "submit_info": "HTTP 10.10.15.25:45410",
                    "last_error": "absentsubscriberSM"
                }
            ]
        }
    }
}

Request: query_subscriber_all

Retrieve from HLR information about a subscriber using all available methods.
For each interrogation type a separate object contains returned information.
CS and PS information is retrieved via AnyTimeInterrogation while SMS information uses SendRoutingInfoForSM.
The subscriber should be identified by MSISDN since this is the primary identity for a SMSC. Identification by IMSI works only if HLR is specified or configured.

Request

This request has multiple formats in which it can be sent:

{
    "request": "query_subscriber_all",
    "params": {
        "msisdn": "Mandatory, string. Phone Number.",
        "hlr": "Optional, string. GT of the HLR to query."
    }
}
{
    "request": "query_subscriber_all",
    "params": {
        "imsi": "Mandatory, string. International Mobile Subscriber Identity.",
        "hlr": "Optional, string. GT of the HLR to query"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "cs": {
            "msisdn": "Phone number.",
            "imei": "May be 15 digit IMEI or 16 digit IMEISV.",
            "imsi": "International Mobile Subscriber Identity.",
            "hlr": "Home Location Register",
            "vlr": "Visitor Location Register",
            "msc": "Mobile Switching Center",
            "cellid": "GSM or UMTS Location (5-6 digits PLMN + 4 xdigits LAC + optional 4 xdigits CellID or SAC)",
            "loc_age": "For MSC information",
            "eps_age": "EPS information may be present in case of LTE combined attach",
            "eps_tai": "Tracking Area Identity (5-6 digits PLMN + 4 xdigits TAC)",
            "eps_cell": "Global Cell Id (5-6 digits PLMN + 7 xdigits CellID)"
        },
        "ps": {
            "msisdn": "Phone number.",
            "imei": "May be 15 digit IMEI or 16 digit IMEISV.",
            "rat_type": "One of: geran, utran, e-utran.",
            "imsi": "International Mobile Subscriber Identity.",
            "hlr": "Home Location Register",
            "sgsn": "Serving GPRS Support Node",
            "mme": "MME Name from MAP or Diameter OriginHost of MME.",
            "loc_age": "For SGSN information (GSM or UMTS)",
            "eps_age": "For MME information (LTE)",
            "eps_tai": "LTE Tracking Area Identity (5-6 digits PLMN + 4 xdigits TAC)",
            "eps_cell": "LTE Global Cell Id (5-6 digits PLMN + 7 xdigits CellID)"
        },
        "sms": {
            "imsi": "International Mobile Subscriber Identity.",
            "hlr": "Home Location Register",
            "msc": "Mobile Switching Center",
            "sgsn": "Serving GPRS Support Node"
        }
    }
}

Errors

{
    "code": 200,
    "message": "Internal retrieval error."
}
{
    "code": 402,
    "message": "Missing both 'msisdn' and 'imsi' parameters."
}

Examples: query_subscriber_all

Orange Dot SMSC API - JSON API for YateSMSC Control

Retrieve information about subscriber that has MSISDN ‘963888810991’.

Request

{
    "request": "query_subscriber_all",
    "node": "smsc",
    "params": {
        "msisdn": "963888810991"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "cs": {
            "msisdn": "963888810991",
            "hlr": "963880043",
            "imei": "3584360706105500",
            "imsi": "001010000010991",
            "loc_num": "555",
            "vlr": "963880042",
            "msc": "963880042",
            "cellid": "001430430041f",
            "loc_age": 1801
        },
        "ps": {
            "msisdn": "963888810991",
            "hlr": "963880043",
            "imsi": "001010000010991"
        },
        "sms": {
            "imsi": "001010000010991",
            "hlr": "963880043",
            "msc": "963880042"
        }
    }
}

Request: query_subscriber_sms

Retrieve from HLR information about a subscriber using SendRoutingInfoForSM.
The subscriber should be identified by MSISDN since this is the primary identity for a SMSC. Identification by IMSI works only if HLR is specified or configured.

Request

{
    "request": "query_subscriber_sms",
    "params": {
        "msisdn": "Mandatory, string. Phone Number.",
        "imsi": "Optional, string. International Mobile Subscriber Identity.",
        "hlr": "Optional, string. GT of the HLR to query."
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "imsi": "International Mobile Subscriber Identity.",
        "hlr": "Home Location Register",
        "msc": "Mobile Switching Center",
        "sgsn": "Serving GPRS Support Node"
    }
}

Errors

{
    "code": 200,
    "message": "Internal retrieval error."
}
{
    "code": 402,
    "message": "Missing both 'msisdn' and 'imsi' parameters."
}

Examples: query_subscriber_sms

Orange Dot

Retrieve from HLR information about subscriber that has MSISDN ‘963888810991’.

Request

{
    "request": "query_subscriber_sms",
    "node": "smsc",
    "params": {
        "msisdn": "963888810991"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "imsi": "001010000010991",
        "hlr": "963880043",
        "msc": "963880042"
    }
}

Request: query_subscriber_cs

Retrieve from HLR the CS information about a subscriber using AnyTimeInterrogation.
The subscriber should be identified by MSISDN. Identification by IMSI works only if HLR is specified or configured.

Request

This request has multiple formats in which it can be sent:

{
    "request": "query_subscriber_cs",
    "params": {
        "msisdn": "Mandatory, string. Phone Number.",
        "hlr": "Optional, string. GT of the HLR to query."
    }
}
{
    "request": "query_subscriber_cs",
    "params": {
        "imsi": "Mandatory, string. International Mobile Subscriber Identity.",
        "hlr": "Optional, string. GT of the HLR to query"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "msisdn": "Phone number.",
        "imei": "May be 15 digit IMEI or 16 digit IMEISV.",
        "imsi": "International Mobile Subscriber Identity.",
        "hlr": "Home Location Register",
        "vlr": "Visitor Location Register",
        "msc": "Mobile Switching Center",
        "cellid": "GSM or UMTS Location (5-6 digits PLMN + 4 xdigits LAC + optional 4 xdigits CellID or SAC)",
        "loc_age": "For MSC information",
        "eps_age": "EPS information may be present in case of LTE combined attach",
        "eps_tai": "Tracking Area Identity (5-6 digits PLMN + 4 xdigits TAC)",
        "eps_cell": "Global Cell Id (5-6 digits PLMN + 7 xdigits CellID)"
    }
}

Errors

{
    "code": 200,
    "message": "Internal retrieval error."
}
{
    "code": 402,
    "message": "Missing both 'msisdn' and 'imsi' parameters."
}

Examples: query_subscriber_cs

Orange Dot

Retrieve from HLR the CS information about subscriber that has MSISDN ‘96388270078’.88810991′.

Request

{
    "request": "query_subscriber_cs",
    "node": "smsc",
    "params": {
        "msisdn": "96388270078"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "msisdn": "96388270078",
        "hlr": "963880043",
        "imsi": "001019901001078"
    }
}

Request: query_subscriber_ps

Retrieve from HLR the PS or EPS information about a subscriber using AnyTimeInterrogation.
The subscriber should be identified by MSISDN. Identification by IMSI works only if HLR is specified or configured.

Request

This request has multiple formats in which it can be sent:

{
    "request": "query_subscriber_ps",
    "params": {
        "msisdn": "Mandatory, string. Phone Number.",
        "hlr": "Optional, string. GT of the HLR to query."
    }
}
{
    "request": "query_subscriber_ps",
    "params": {
        "imsi": "Mandatory, string. International Mobile Subscriber Identity.",
        "hlr": "Optional, string. GT of the HLR to query"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "msisdn": "Phone number.",
        "imei": "May be 15 digit IMEI or 16 digit IMEISV.",
        "rat_type": "One of: geran, utran, e-utran.",
        "imsi": "International Mobile Subscriber Identity.",
        "hlr": "Home Location Register",
        "sgsn": "Serving GPRS Support Node",
        "mme": "MME Name from MAP or Diameter OriginHost of MME.",
        "loc_age": "For SGSN information (GSM or UMTS)",
        "eps_age": "For MME information (LTE)",
        "eps_tai": "LTE Tracking Area Identity (5-6 digits PLMN + 4 xdigits TAC)",
        "eps_cell": "LTE Global Cell Id (5-6 digits PLMN + 7 xdigits CellID)"
    }
}

Errors

{
    "code": 200,
    "message": "Internal retrieval error."
}
{
    "code": 402,
    "message": "Missing both 'msisdn' and 'imsi' parameters."
}

Examples: query_subscriber_ps

Orange Dot

Retrieve from HLR the PS or EPS information about subscriber that has MSISDN ‘963880100’.

Request

{
    "request": "query_subscriber_ps",
    "node": "smsc",
    "params": {
        "msisdn": "963880100"
    }
}

Response

{
    "code": 0,
    "subscriber_info": {
        "msisdn": "963880100",
        "hlr": "963880043",
        "imei": "3516760300876402",
        "rat_type": "geran",
        "imsi": "417990000000000",
        "sgsn": "963880042",
        "loc_age": 32767
    }
}

This documentation was generated on 07 June 2022