Skip to main content

What You Can Do with the MNP APIs

The HORISEN MNP API Suite gives you two independent ways to resolve Mobile Number Portability (MNP) data — a synchronous HTTP lookup and a DNS-based ENUM lookup — available both as a Customer integration (querying HORISEN) and as a Supplier integration (letting HORISEN query you).

Resolve MNP via HTTP (Customer)​

  • Query MCC/MNC for a given MSISDN over a simple HTTP GET request.
  • Optionally retrieve country and operator name via the opinfo parameter.
  • Get ported, roaming, valid, and online status flags in the response.
  • Distinguish reliable answers (RC_OK) from prefix-database fallbacks (RC_UNRELIABLE).

Resolve MNP via ENUM/DNS (Customer)​

  • Query MCC/MNC using standard ENUM (E.164-to-domain) DNS NAPTR lookups.
  • A good fit if your infrastructure is already integrated with ENUM/SIP systems.
  • Authenticate by IP address and port only — no credentials are sent in the query itself.

Provide MNP Data as a Supplier (HTTP)​

  • Expose an HTTP service that the HORISEN MNP Server queries via GET /number-lookup.
  • Authenticate incoming requests with a Base64-encoded API Key over Basic auth, or restrict access via VPN.
  • Return MCC, MNC, country, operator, and number type for each queried MSISDN.

Provide MNP Data as a Supplier (ENUM/DNS)​

  • Expose an ENUM/DNS service that the HORISEN MNP Server queries via NAPTR lookups.
  • Whitelist the HORISEN MNP Server's IP address for authentication — no request-level credentials needed.
  • Return MCC/MNC (or SPID) mappings, plus ported status.

MNP API Suite Modules​

API ModuleDescription
MNP Customer HTTP APISynchronous HTTP GET lookup for MCC/MNC, ported/roaming/valid/online status, and optionally country/operator.
MNP Customer ENUM APIDNS-based ENUM (NAPTR) lookup for MCC/MNC, SPID, and ported status.
MNP Supplier HTTP APILets a Supplier expose an HTTP number-lookup service that HORISEN queries.
MNP Supplier ENUM APILets a Supplier expose an ENUM/DNS service that HORISEN queries via NAPTR.

Authentication​

Each API uses a different authentication method:

  • Customer HTTP API — user and password sent as GET query parameters.
  • Customer ENUM API and Supplier ENUM API — the client's IP address and port must be whitelisted in advance; no credentials are sent in the query itself.
  • Supplier HTTP API — Basic authentication with a Base64-encoded API Key in the Authorization header, or VPN access to the Supplier's service.

Example Lookups​

MNP Lookup (Customer HTTP API)​

https://mnp1.horisen.com:16089/mnpjson?msisdn=41787078880&user=testuser&password=testpass

Example response:

{
    "imm": {
        "qid": "135c5eea40008a01807c7229938dd852",
        "msisdn": "41787078880",
        "mcc": "228",
        "mnc": "03",
        "errcode": "000",
        "errdesc": ""
    }
}

ENUM Lookup (Customer ENUM API)​

dig @194.0.137.85 -p 16090 -t naptr 0.8.8.8.7.0.7.8.7.1.4.enum.horisen.com

The NAPTR answer returns the MCC/MNC pair embedded in the TEL URI, e.g. mcc=228;mnc=02.

Supplier API Examples​

Number Lookup (Supplier HTTP API)​

curl -X 'GET' \
'https://mnp.example.com/horisen-mnp/v1/number-lookup?msisdn=525614157575' \
-H 'Authorization: Basic BASE64_API_KEY'

Example response:

{
  "number": "525614157575",
  "ported": true,
  "mcc": "334",
  "mnc": "20",
  "country": "Mexico",
  "operator": "TELCEL",
  "numbertype": "mobile"
}

NAPTR Query (Supplier ENUM API)​

dig @SUPPLIER_ENUM_ADDRESS -p SUPPLIER_ENUM_PORT -t naptr 0.8.8.8.7.0.7.8.7.1.4.SUPPLIER_DOMAIN

Typical Integrations​

SMS / Voice Routing Engines​

Use MCC/MNC and ported status from either Customer API to select the correct downstream route and avoid misrouting.

Fraud & Compliance Systems​

Verify number validity and portability status before processing transactions or messages.

CRM & Billing Systems​

Enrich customer records with operator and country metadata.

Upstream Data Provisioning​

Implement the Supplier HTTP or ENUM API so HORISEN can resolve numbers against your own MNP database in real time, without needing bulk data transfers.

Use Cases​

Use the MNP APIs to:

  • Resolve MSISDN operator/portability data in real time — call the Customer HTTP API (/mnpjson) or the Customer ENUM API (DNS NAPTR lookup) to get MCC/MNC before routing SMS or voice traffic.
  • Improve routing accuracy — use the ported, roaming, and valid flags from the Customer HTTP API response to avoid misrouting and reduce delivery failures.
  • Display operator/country info to end users or agents — pass opinfo=true on the Customer HTTP API to also receive country and operator fields in the response.
  • Fall back gracefully when a reliable answer isn't available — check for the RC_UNRELIABLE code, which indicates the MCC/MNC was derived from the prefix database rather than a live portability source.
  • Become an MNP data source for HORISEN — implement the Supplier HTTP API (GET /number-lookup) or the Supplier ENUM API (NAPTR responses) so HORISEN can query your MNP database directly, instead of exchanging bulk data files.