Number Verifier

1. General Information

The Number Verifier service is designed to validate mobile phone numbers by checking their live status, current serving operator, country and number portability indicator.

Integration is available via two methods: HTTP API and ENUM API.

The service supports IP- and port-based authentication and offers test endpoints to verify integration correctness.

2. HTTP API

2.1. Authentication

HTTP API queries require authentication to identify the client, return appropriate results and ensure security.

Authentication is based on the client's IP address, as specified in their profile, and the port used during the query.

Prior to using the HTTP API for Number Verifier queries (in both test and production environments), the client should submit a list of IP addresses to their account manager for authentication purposes.

2.2. Query Format

Production:

*HTTP API also allows selecting a tariff by sending its code in the query (optional, only for clients with multiple tariffs).

Testing:

{NUMBER} represents the MSISDN (telephone number in international format) without the “+” sign.

{TARIFF_ID} represents the code of the tariff in the BSG system.

2.3. Retrieving Number Verifier Resolution for a Number

Description:Returns information about a mobile number including its country, MCC/MNC, current serving operator, number portability indicator, live status and additional attributes (refer to Section 5 for details).

2.3.1. Query Example (production):

Standard query:

https://hlr.bsg.world:5011/msisdn/380123456789
              

Optional query (with tariff ID):

https://hlr.bsg.world:5011/msisdn/380123456789/tariff/22
              

2.3.2. Query Example (testing):

https://hlr-test.bsg.world:5013/msisdn/380123456789
              

2.3.3. Response Example

Success:

{
  "tn": "380123456789"
  "cc": "UA"
  "cn": "lifecell"
  "mcc": "255"
  "mnc": "06"
  "sii": 1
  "npi": false
  "nt": "mobile"
  "ls": "000"
  "rc": "000"
}
              

Error (only for Reason Code ranges 100 - 199):

{
  "tn": "380123456789"
  "cc": "UA"
  "cn": "lifecell"
  "mcc": "255"
  "mnc": "06"
  "sii": 1
  "npi": false
  "nt": "mobile"
  "ls": "201"
  "rc": "120"
}
              

Error (only for Reason Code ranges 010 - 070):

{
  "rc": "010"
}
              

Note: Refer to Sections 5–7 for details on the definition of the response fields.

3. ENUM API

3.1. Authentication

ENUM API queries require authentication to identify the client, return appropriate results and ensure security.

Authentication is based on the client's IP address, as specified in their profile, and the port used during the query.

Prior to using the ENUM API for Number Verifier queries (in both test and production environments), the client should submit a list of IP addresses to their account manager for authentication purposes.

3.2. Query Format

Production:

Testing:

{NUMBER} represents the MSISDN (telephone number in international format) without the “+” sign.

Note: Queried MSISDN must be reversed and dot-separated (e.g., 380123456789 → 9.8.7.6.5.4.3.2.1.0.8.3).

3.3. Retrieving Number Verifier Resolution for a Number

Description: Returns information about a mobile number including its country, MCC/MNC, current serving operator, number portability indicator, live status and additional attributes (refer to Section 5 for details).

3.3.1. Query Example (production):

dig @141.95.255.235 -p 5001 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
              

3.3.2. Query Example (testing):

dig @141.95.255.235 -p 5003 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
              

3.3.3. Response Example:

Success:

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5001 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 38477
;; flags: qr; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;9.8.7.6.5.4.3.2.1.0.8.3.enum.   IN  NAPTR

;; ANSWER SECTION:
9.8.7.6.5.4.3.2.1.0.8.3.enum. 300 IN NAPTR 100 10 "U" "E2U+pstn:tel" "!^.*$!tn:380123456789;cc:UA;cn:lifecell;mcc:255;mnc:06;sii:1;npi:false;nt:mobile;ls:000;rc:000!" .

;; Query time: 32 msec
;; SERVER: 141.95.255.235#5001(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 174
              

Error (only for Reason Code ranges 100 - 199):

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5001 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 44972
;; flags: qr; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;9.8.7.6.5.4.3.2.1.0.8.3.enum.   IN  NAPTR

;; ANSWER SECTION:
9.8.7.6.5.4.3.2.1.0.8.3.enum. 300 IN NAPTR 100 10 "U" "E2U+pstn:tel" "!^.*$!tn:380123456789;cc:UA;cn:lifecell;mcc:255;mnc:06;sii:1;npi:false;nt:mobile;ls:201;rc:120!" .

;; Query time: 38 msec
;; SERVER: 141.95.255.235#5001(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 174
              

Error (only for Reason Code ranges 010 - 070):

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5001 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 80127
;; flags: qr; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;9.8.7.6.5.4.3.2.1.0.8.3.enum.   IN  NAPTR

;; ANSWER SECTION:
9.8.7.6.5.4.3.2.1.0.8.3.enum. 300 IN NAPTR 100 10 "U" "E2U+pstn:tel" "!^.*$!rc:013!" .

;; Query time: 51 msec
;; SERVER: 141.95.255.235#5001(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 78
              

Note: Refer to Sections 5–7 for details on the definition of the response fields.

4. Testing the Integration Setup

Test endpoints are available for verifying your HTTP and ENUM API integration. They let you check authorization, connectivity, and correct query/response formatting.

As in production, access to the test environment is granted only to pre-submitted client IPs.

Note: Refer to Sections 2.2. and 3.2. for details about the test endpoints.

Note: The test responses do not contain real subscriber data and include the following information:

• cc — real, provided based on the prefix of the queried number;

• the rest of the parameters (cn, mcc, mnc, sii, npi, nt, ls, rc, etc) – not real, test values.

5. Number Verifier Response Fields

6. Live Status

The Live Status ls field indicates whether a mobile number is currently active on the network. This service dynamically queries the HLR (Home Location Register) of the target operator via the SS7 network to verify the status of the mobile number and retrieve information about the associated subscriber.

The table below lists current field values and supports future expansion as new live statuses or services become available.

7. Reason Code

The Reason Code rc field provides additional information relating to how a query was processed within the BSG system. These codes may indicate failure reasons (such as an invalid number length) or provide other relevant information.

The table below lists current field values and supports future expansion as new reason codes or services become available.