Developer Docs

Table of contents

Send Number Verifier request

HLR (Home Location Register) is a centralized database that contains detailed information about each subscriber of a certain GSM operator’s network.

Number Verifier API allows you to send network queries to HLR to verify a mobile phone number. This will allows obtaining information that the mobile phone number is active and registered in the mobile network in a real time mode.

Single Number Verifier request

To send Number Verifier request, make a request to this URL:

PUT (POST) https://api.bsg.world/rest/hlr/create

Request parameters:

ParameterRequiredTypeDescription 
msisdnYesstringThe phone number to which the Number Verifier request is sent.
referenceYesstringNumber Verifier request external ID. A string of up to 32 characters containing /a-zA-Z0-9/.
tariffNointegerTariff number. The default is 0. An integer from 0 to 9.
callback_urlNostringRedefines the link where information on the Number Verifier request will be sent.

Request example:

[{
   "msisdn":"85267202829",
   "reference":"sendHLR0407",
   "tariff":9
   "callback_url":"https://somelink.com/hlr"
}]

Response parameters:

ParameterTypeDescription 
id integerRequest ID.
pricefloatNumber Verifier request cost
currencystringThe currency of the account, in which the Number Verifier cost is specified.

If the request is successful, you will receive a response:

{
  "error": "0",
  "id": "12123",
  "price": "0.002",
  "currency": "EUR"
}

Send a synchronous Number Verifier request

The method allows creating a Number Verifier request to check the number and get the verifier result immediately. To send Number Verifier request synchronously, make a request to this URL:

PUT (POST) https://api.bsg.world/rest/hlr/check

Request parameters:

ParameterRequiredTypeDescription 
msisdnYesstringThe phone number to which the Number Verifier request is sent.
tariffNointegerTariff number. The default is 0. An integer from 0 to 9.

Request example:

{
   "msisdn":"85267202829",
   "tariff":9
}

Response parameters:

ParameterTypeDescription 
id integerInternal Number Verifier request ID.
country_namestringCountry name.
brandstringOperator (e.g. “Vodafone”).
brand_namestringOperator name (e.g. “PrJSC VF Ukraine”).
referencestringExternal Number Verifier request ID.
msisdnstringPhone number for which the Number Verifier request is performed.
networkstringMCC and MNC numbers (for absent and active statuses).
statusstringRequest status. Possible values: sent, absent, active, unknown, failed.
detailsstringNumber Verifier request details (full information is available when the status is active).
imsistringInternational Mobile Subscriber Identifier (Individual Subscriber Number) associated with each GSM, UMTS or CDMA mobile communication user.
portedbooleanIndicator whether the phone is ported or not (1 – ported, 0 – not).
roamingbooleanIndicator whether the phone is roaming or not. (1 – roaming, 0 – not).
createdDatetimestringDate when the Number Verifier request was created. Display format – Y-m-d H:i:s
statusDatetimestringDate and time when the Number verification status was received. (1 – roaming, 0 – not).
pricefloatNumber Verifier request cost
currencystringThe currency of the account, in which the Number Verifier request cost is specified.

If the request is successful, you will receive a response:

{
   "error":0,
   "errorDescription":"No errors",
   "id":"271811729",
   "reference":null,
   "msisdn":"380505142320",
   "network":null,
   "status":"active",
   "details":null,
   "createdDatetime":null,
   "statusDatetime":null
}

Send bulk Number Verifier

To send Bulk Number Verifier, make a request to this URL:

PUT (POST) https://api.bsg.world/rest/hlr/create

Request parameters:

The data array of the following structure is passed:

ParameterRequiredTypeDescription
msisdnYesstringPhone number for which the Number Verifier request is performed.
referenceYesstringNumber Verifier external request ID. A string of up to 32 characters containing /a-zA-Z0-9/.
tariffNointegerTariff number. The default is 0. An integer from 0 to 9.
callback_urlNostringRedefines the link where information on the Number Verifier request will be sent.

Request example:

[
   {
      "msisdn":"85267202829", 
      "reference":"extid13423now"
      "tariff":9,
      "callback_url":"http://someurl.com/callback/?id=12345"},
   },
   {
      "msisdn":"85267202829", 
      "reference":"extid13425"
      "tariff":9,
      "callback_url":"http://someurl.com/callback/?id=12346"}
   }
]

Response parameters:

ParameterTypeDescription 
referencestringNumber Verifier request external ID.
id integerRequest ID.
pricefloatNumber Verifier request cost
currencystringThe currency of the account, in which the Number Verifier request cost is specified.

If the request is successful, you will receive a response:

{
  "result": [
    {
      "reference": "extid13423now",
      "id": "12345",
      "error": "0",
      "price": "0.002",
      "currency": "EUR"
    },
    {
      "reference": "extid13425",
      "id": "12346",
      "error": "0",
      "price": "0.002",
      "currency": "EUR"
    }
  ],
  "error": "0",
  "totalprice": "0.004",
  "currency": "EUR"
}