HLR API

Sending an asynchronous HLR request

For information about the authentication and authorization procedures that associate API calls with the required applications in your account, see Authorization.

Request:

Parameters can be passed in the request headers:

POST/GET https://api.unibell.ru/v2/hlr?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX

Or in the request body:

{
    "destAddr": "7XXXXXXXXXX"
}

Example requests using CURL:

curl --location --request POST 'https://api.unibell.ru/v2/hlr?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX'

curl --location 'https://api.unibell.ru/v2/hlr' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "destAddr": "7XXXXXXXXXX"
}'

Parameter	Type	Description
destAddr	string	Phone number to which the HLR request was sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX

Response upon successful request execution:

{
    "status": "Created",
    "requestId": "11273"
}

Response in case destAddr is missing:

{
    "status": "Rejected",
    "error": "Missing destAddr param"
}

Parameter	Type	Description
status	string	Request status: _{Created – The message has been created in the system but not yet sent Rejected – The message was not accepted for sending, see error for details prohibitedForServiceError – The key does not belong to the HLR service invalidAccessKeyError – Authorization key error}
requestId	string	Unique request identifier
error	string	Error description: _{Missing destAddr param – destAddr is missing in the request}

Sending a synchronous HLR request

A synchronous request — the system returns a response immediately within the same request.

Request:

Parameters can be passed in the request headers:

POST/GET https://api.unibell.ru/v3/hlr?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX

Or in the request body:

{
    "destAddr": "7XXXXXXXXXX"
}

Example requests using CURL:

curl --location --request POST 'https://api.unibell.ru/v3/hlr?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX'

curl --location 'https://api.unibell.ru/v3/hlr' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "destAddr": "7XXXXXXXXXX"
}'

Response upon successful request execution:

{
    "id": 9654,
    "destAddr": "7XXXXXXXXXX",
    "requestId": "11273",
    "status": "Delivered",
    "networkErrCode": 0,
    "mcc": 250,
    "mnc": 2,
    "originalMcc": 250,
    "originalMnc": 20,
    "ported": 1
}

Parameter	Type	Description
id	integer	Unique HLR identifier
destAddr	string	Phone number to which the HLR request was sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX
requestId	string	Unique request identifier
status	string	HLR request status: _{Delivered – Phone is active Expired – Waiting time for network response expired Deleted – Request canceled before receiving result Undeliverable – Phone is inactive Accepted – Request sent, but network result not yet received Unknown – Unknown error Rejected – Request rejected by the network, check impossible}
networkErrCode	string	SS7 errors, see below
mcc	integer	Mobile Country Code
mnc	integer	Mobile Network Code – mobile operator code
originalMcc	integer	MCC of the original operator ^{Country code of the mobile network where the subscriber was initially registered}
originalMnc	integer	MNC of the original operator ^{Mobile operator code within the country where the subscriber was initially registered}
ported	integer	Indicates whether the number has been ported: _{1 – if the number was ported 0 – if not ported}

Retrieving status

Request:

Parameters can be passed in the request headers:

GET https://api.unibell.ru/v2/hlr_status?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&requestId=11273

As well as in the request body:

{
    "requestId": "11273"
}

Example requests using CURL:

curl --location 'https://api.unibell.ru/v2/hlr_status?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX&requestId=11273'

curl --location --request GET 'https://api.unibell.ru/v2/hlr_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "11273"
}'

Response body upon successful request execution:

{
    "id": 9654,
    "destAddr": "7XXXXXXXXXX",
    "requestId": "11273",
    "status": "Rejected",
    "networkErrCode": 34,
    "mcc": 0,
    "mnc": 0,
    "ported": 0
}

Response in case the requestId parameter is missing:

{
    "status": "Rejected",
    "error": "Missing requestId param"
}

Parameter	Type	Description
id	integer	Unique HLR identifier
destAddr	string	Phone number to which the HLR request was sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX
requestId	string	Unique request identifier
status	string	HLR request status: _{Created – Request created in the system but not yet sent Enroute – Request is being processed, awaiting network verification Delivered – Phone is active Expired – Waiting time for network response expired Deleted – Request canceled before receiving result Undeliverable – Phone is inactive Accepted – Request sent, but network result not yet received Unknown – Unknown error Rejected – Request rejected by the network, check impossible notFound – Record for the requested requestId does not exist/not found}
networkErrCode	string	SS7 errors, see below
mcc	integer	Mobile Country Code – код страны
mnc	integer	Mobile Network Code – mobile operator code
ported	integer	Indicates whether the number has been ported: _{1 – if the number was ported 0 – if not ported}
error	string	Error description: _{Missing requestId param – requestId is missing in the request}

Retrieving request statuses via Webhook

Request source:

Webhooks will be sent from the IP addresses 185.175.44.211 and 46.148.235.62, which must be added to the ACL on the client’s web server to ensure proper interaction.

Interaction format:

Callbacks are performed over the HTTP protocol.

Data is transmitted in JSON format.

Webhook setup is performed by submitting a request to technical support.

Sending a request:

The request is sent in JSON format, which has the following structure:

{
  "ported": 0,
  "mnc": 0,
  "requestId": "35714061",
  "destAddr": "7XXXXXXXXXX",
  "id": 639073386,
  "networkErrCode": 0,
  "mcc": 0,
  "status": "Delivered"
}

Parameter	Type	Description
ported	integer	Indicates whether the number has been ported: _{1 – if the number was ported 0 – if not ported}
mnc	integer	Mobile Network Code – mobile operator code
requestId	string	Unique request identifier
destAddr	string	Phone number to which the HLR was sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX
id	integer	Unique HLR identifier
networkErrCode	string	SS7 errors, see below
mcc	integer	Mobile Country Code
status	string	HLR request status: _{Created – Request created in the system but not yet sent Enroute – Request is being processed, awaiting network verification Delivered – Phone is active Expired – Waiting time for network response expired Deleted – Request canceled before receiving result Undeliverable – Phone is inactive Accepted – Request sent, but network result not yet received Unknown – Unknown error Rejected – Request rejected by the network, check impossible}

Error codes in status

Possible error codes in the HLR status (networkErrCode).

All unspecified codes are considered vendor-dependent and are not handled separately.

Code	Description Key	Description
1	unknownSubscriber	Unknown subscriber _{The subscriber is not registered in the network}
5	unidentifiedSubscriber	Unidentified subscriber _{Subscriber is registered, but information about them is missing or unavailable}
9	illegalSubscriber	Illegal subscriber _{Access denied due to rule violation}
11	teleserviceNotProvisioned	Telecommunication service not provisioned _{Subscriber is not subscribed to the requested service}
13	callBarred	Call barred _{Calls are prohibited for this subscriber (e.g., due to blocking or tariff restrictions)}
21	facilityNotSupported	Facility not supported _{Requested service is unavailable for the subscriber or network}
27	adsentSubscriber	Address absent _{Message not delivered due to missing sender information}
31	subscriberBusyForMT-SMS	Subscriber busy for MT-HLR _{Subscriber cannot receive HLR due to device being busy}
32	sm-DeliverFailure	HLR delivery failure _{General error related to HLR transmission}
33	messageWaitingListFull	Message waiting list full _{Subscriber device memory has no space for new messages}
34	systemFailure	System failure _{General network-side error}
35	dataMissing	Data missing _{Insufficient information to complete the operation}
36	unexpectedDataValue	Unexpected data value _{Incorrect or unexpected data provided}

On this page