Developer Tools
  • Home
  • Text SMS
  • HLR
  • Sample Code
  • Introduction
  • Request Method
  • SMPP
  • HTTP
  • Status Code Table1
  • Status Code Table2

HLR LOOKUP API

Introduction - HLR LOOKUP API

The Home Location Register (HLR) is the main database of permanent subscriber information for a mobile network. The HLR is an integral component of CDMA (code division multiple access), TDMA (time division multiple access), and GSM (Global System for Mobile communications) networks.

Request Methods

System Requests can be made by following two methods:

  • SMPP

  • HTTP

SMPP

The Short Message Peer-to-Peer (SMPP) is a protocol used by the telecommunications industry for exchanging SMS messages between Short Message Service Centers (SMSC) and External Short Messaging Entities (ESME). The protocol is a level-7 TCP/IP protocol, which allows fast delivery of SMS messages. The connection between application and AMS SMPP Server is SMPP version 3.4 Using SMPP Account, It is possible to Request for Number Lookup. In order to Use SMPP Lookup Service, User must have valid systemid & password to Set in Bind PDU.

BIND Operation

The purpose of the SMPP bind operation is to register an instance of an ESME with the SMSC system and request an SMPP session over this network connection for the submission or delivery of messages. Thus, the Bind operation may be viewed as a form of SMSC login request to authenticate the ESME entity wishing to establish a connection.

Requested Parameters:

System_id = Provided System Id

Password = Provided Password

System_type = HLR

BIND Mode

User may bind as either Tx (Transmitter), Rx (Receiver) or TRx (Transceiver).

Tx: User bound as a Transmitter is authorized to send short messages and to receive the corresponding SMPP responses.

Rx:User bound as a Receiver is authorized to receive short messages and to return the corresponding SMPP message responses.

TRx: User bound as a Transceiver is allowed to send & receive messages over a single SMPP session.

Users are allowed to bound as only 1 TRx/Rx with multiple Tx Session.

SUBMIT Operation

SubmitSM PDU is used for submitting the number context Request, having destAddress parameter set to the required destination address. All other parameters (srcAddress, esm, ton/npi) will be ignored.

submitSMResp PDU will be used as Response containing responseid (Unique Number to Identify Request) on Successful Submission or Submit_Error in case of any Error. The command_status field of an SMPP message response indicates the success or failure of an SMPP request.

SMPP Error Codes and their associated values are defined in the following table:

Code Name Description
0x00000000ESME_ROK No Error
0x00000003ESME_RINVCMDID Invalid Command ID
0x00000008ESME_RSYSERRSystem Error
0x00000010ESME_RINSBAL Insufficient Balance
0x0000000BESME_RINVDSTADR Invalid Destination Address
0x0000000DESME_RBINDFAILBind Failed
0x0000000EESME_RINVPASWDInvalid Password
0x0000000FESME_RINVSYSID Invalid System ID
0x00000012ESME_RCOVERR No Coverage For Requested Destination
0x00000016ESME_RACCEXPIRYAccount Expired
Lookup Result

Once the Lookup request is being finalized on our System, deliverSM PDU is sent as a lookup Result containing the Status & other required information included in the short_message field of the deliverSM for the requested destination number.

Example:

(deliver: (pdu: 224 5 0 5001) (addr: 0 0 HLR) (addr: 0 0 919589xxxxxx) (sm: msg: id:6002 sub:001 dlvrd:001 submit date:1507140141 done date:1507140142 stat:DELIVRD err:000 cc:91 nnc:40493 isPorted:false p_nnc: isRoaming:false r_cc: r_nnc: text:dlr ) (opt: (str: (tlv: 30) 6002) ) )

If Number is INVALID/ABSENT_SUBSCRIBER etc, The DeliverSm will be as follow:

(deliver: (pdu: 224 5 0 5000) (addr: 0 0 HLR) (addr: 0 0 919589xxxxxx) (sm: msg: id:6000 sub:001 dlvrd:001 submit date:1507141154 done date:1507141225 stat:UNDELIV err:011 cc:91 nnc:40493 isPorted:false p_nnc: isRoaming:false r_cc: r_nnc: text:dlr ) (opt: (str: (tlv: 30) 6000) ) )

Here err: 011 is the status code of the Lookup. See the status code table for description.

HTTP

Users can Use Following Services via HTTP API:

1) Number Lookup

2) Status Enquiry

1) Number Lookup :

Number Lookup HTTP API supports both GET and POST Methods. Using HTTP Method limit of upto 100 numbers is allowed in a single request.

Description:

URL For Lookup Request:

http://ip:port/websmpp/hlr/lookup?username=xxxx&password=xxxx &destination=919589xxxxxx

Requested Parameters:

username = Provided System Id

Password = Provided Password

Destination = Destination Number or Comma separated Destination Numbers

Response Format

On Successful Lookup:

BatchId: 140715134158696

On Failed:

ERROR - HTTP01 --> Invalid HTTP URL Format

2) Status Enquiry :

After Successful Lookup, User can get Result via Following URL:

http://ip:port/websmpp/hlr/report?batchid=140715134158696

Result Format will be JSON (JavaScript Object Notation):

{"cc":"91","nnc":"40493","isRoaming":"No","isPorted":"No","destination":"919 589xxxxxx","error_code":"000","id":6002,"time":"2015-07-14 13:41:59","batchid":"140715134158696","status":"DELIVRD"}

Parameter Description:

Id : Unique Id to Identify this request

batchid: Batch id provided at request time

destination: Requested Destination Number

time: lookup request time

status: status of the number

error_code: error code if lookup failed/number error

error: error description if lookup failed/number error

cc: Country code of destination number

nnc: Network code

isPorted: Yes/No

p_nnc: ported network code if ported

isRoaming: Yes/No

r_cc: Roaming Country code if roaming

r_nnc: Roaming Network code if roaming

Status Code Table (1)

This section Describes Errors Returned as Response On Submission (if Failed):

Code Name Description
001INVALID_LOGIN Either Systemid or password is incorrect
002INVALID_REQUEST Required parameters are missing or Invalid parameters or invalid values of parameters
003ACCOUNT_EXPIREDThe Account has been Expired
004INSUF_BALANCEInsufficient Balance to fulfill the Request
005INVALID_DEST_ADDR Invalid Destination Address
006NO_COVERAGENo Coverage for Requested Destination
007SYSTEM_ERRORSystem Error Occurred
Status Code Table (2)

This section describes Status of the Lookup Result returned by the system.

Code Name Description
011ABSENT_SUBSCRIBERThe Subscriber is absent
012UNKNOWN_SUBSCRIBER The subscriber is unknown
013UNIDENTIFIED_SUBSCRIBERThe Subscriber is unindentified
014TIMEOUTTimeout occurred
015PROVIDER_GENERAL_ERRORGeneral Error From Provider
016NO_RESPONSENo Status From Provider
017SYSTEM_FAILUREA system failure occurred.
018INVALID_MSISDNInvalid msisdn
019CALL_BARREDCall Barred
020ILLEGAL_SUBSCRIBERIllegal Subscriber
021TELESERVICE_NOT_PROVISIONEDTeleservice not provisioned
022FACILITY_NOT_SUPPORTEDNo facility
023SUBSCRIBER_BUSY_FOR_MT_SMSSubscriber Busy
024UNEXPECTED_DATA_VALUEUnexpected data
© 2021 | All Rights Reserved. Broadnet