MNP

1. General Information

The MNP Lookup service is designed to identify the current serving operator, country, and number portability status of a mobile phone number.

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 MNP Lookup 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 BSG system.

2.3. Retrieving MNP Lookup Resolution for a Number

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

2.3.1. Query Example (production):

Standard query:

https://mnp.bsg.world:5010/msisdn/380123456789
              

Optional query (with tariff ID):

https://mnp.bsg.world:5010/msisdn/380123456789/tariff/22
              

2.3.2. Query Example (testing):

https://mnp-test.bsg.world:5012/msisdn/380123456789
              

2.3.3. Response Example

Success:

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

Error (Reason Code ranges 010 - 070):

{
  "rc": "010"
}
              

Note: Refer to Sections 5–6 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 MNP Lookup 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 MNP Resolution for a Number

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

3.3.1. Query Example (production):

dig @141.95.255.235 -p 5000 -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 5002 -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 5000 -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: 49443
;; 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:2;npi:false;nt:mobile;rc:000!" .

;; Query time: 53 msec
;; SERVER: 141.95.255.235#5000(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 167
              

Error (Reason Code ranges 010 - 070):

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5000 -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: 30411
;; 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: 48 msec
;; SERVER: 141.95.255.235#5000(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 78
              

Note: Refer to Sections 5–6 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, rc, etc) – not real, test values.

5. MNP Lookup Response Fields

6. 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.