HTTP Interface

1. Overview

This document provides details on the HTTP/S query interface for num-iD's identify and verify products.

The service is primarily designed to enhance customers' Voice & SMS routing and support applications requiring accurate number validation.

Customers can query the identify and verify services through num-iD's Global Points of Presence (PoPs). Along with HTTP/S, the service also supports ENUM query protocols. num-iD offers multiple product options, enabling users to retrieve information about the routing, ownership and status of E.164 telephone numbers.

2. Service Access

2.1. IP Access and Endpoint URLs

The mobile number portability query service is accessible through num-iD PoPs over the public Internet.

Customers can select from any or all available num-iD PoPs to reduce query latency and improve resilience. The full list of PoPs can be obtained by contacting num-iD Sales or Support. Clients who have registered fixed source IPs with num-iD are permitted to use any of the PoPs.

2.2. Authorization for Queries

Customer queries can be authenticated through several methods:

• Registered IP Authorization: num-iD registers the customer's source IP addresses, and only queries from these authorized IPs are permitted.
• User/Password Authorization: num-iD supplies a user/password combination, which must be included with every query.
• Token-Based Authorization: num-iD issues a user/password to obtain a secure token. This token must be included in queries to authenticate the service. Tokens have a set expiration period based on the service being accessed and must be renewed periodically.

The preferred method of customer authorization is determined during the provisioning process.

2.3. Preferred Authentication Method

When accessing the num-iD system using only user/password or token authentication (i.e., without fixed IP addresses), the system imposes stricter limits on both capacity and resilience to protect against potential risks such as DDoS attacks. To mitigate these risks, the following recommendations are made:

• Registered Fixed IPs: Where possible, customers should utilize fixed IP addresses registered with the num-iD system to enhance security and reliability.
• IP Management: Support requests can be made to add or remove source IP addresses as needed.
• Resilience: Customers using fixed IP addresses are encouraged to direct queries to every PoP for optimal redundancy and resilience.
• User/Pass or Token Authentication: These methods should only be used when it's not feasible to register fixed IPs, such as in cases where query sources cannot be easily determined due to the application's nature. Token-based authentication is preferred over user/password for unregistered IPs, and user/password should only be considered when token usage is not possible.
• Security Risks: Those opting for user/password authentication should be aware that this method carries a higher data security risk, and by choosing this approach, customers implicitly accept these risks.

Additionally, customers can configure multiple access types based on the service, origin point, and specific use case. num-iD will assist in determining the most appropriate setup if needed.

3. HTTP Status Codes

The system will return one of the following HTTP responses based on the customer's query. For customers who have the Reason Code feature enabled, a 'failed' query will return a 200 response along with additional details explaining the failure in the Reason Code field:

4. Selecting products

The HTTP query interface offers a range of products and options. Each product may have its own set of commercial terms and service features, and may return different responses for the same E.164 telephone number. num-iD also offers customized responses based on specific customer needs, which may include adjustments to data sources, response fields or service logic. While standard products are available, customizations are possible to better align with customer requirements. Details on the standard query types can be found later in this document.

Customers can select the desired query type by including a 'Service Identifier' as part of their query in the following format:

https://api.num-id.com/query/<number>?service=<service>

Please note that customers must be authorized to use each specific service type. The service identifier for each available service type is listed in the descriptions below.

4.1. Release codes

Release codes offer extra details about how a query was processed within the num-iD system. These codes can explain failure reasons or provide other general information. A full list of the current reason codes is available in the document titled 'Response parameters and values'.

For some MNP destinations, num-iD relies on third-party providers to conduct remote queries. Should the third-party provider fail to deliver a response, num-iD will either return a 'Supplier Timeout' reason code (if reason codes are enabled) or issue a 404 – Not Found error, without providing any number information.

5. Query types and example responses

The following sections outline the different query services accessible through the num-iD HTTP interface. Detailed explanations of the fields returned for each query type are available in the document titled 'Response parameters and values'.

5.1. Numbering Range Information (NRI)

The NRI query utilizes the num-iD Numbering Range Information database, regularly updated with data from regulators, industry bodies, traffic tests and customer feedback.

The NRI query checks that the telephone number (tn) is:

• Correctly formatted (E.164 standard)
• Within the valid length for its range
• Part of a range officially allocated to a service provider by a national regulator (Operator of Record, or)

Primarily used for basic number validation (e.g., customer sign-ups, OBR validation, B-number fraud checks), the NRI also supports routing where number portability is not required.

NRI verifies that a telephone number (TN) falls within an officially assigned number range, but does not confirm whether the TN is actively assigned to a subscriber.

Below is an example of an NRI query made to a valid number. For invalid numbers, a corresponding reason code will be provided, indicating why the NRI query was unsuccessful.

curl "https://api.num-id.com/query/351923XXXXXX?service=nri"

# Response (HTTP 201)
{
  "tn":  "351923******",
  "mcc": "268",
  "mnc": "03",
  "oc":  "PT",
  "od":  "86200055",
  "on":  "NOS (OPTIMUS - COMUNICACOES) (03)",
  "nt":  "mobile",
  "pdi": false,
  "pi":  false,
  "rc":  "1-00"
}

5.2. Mobile Number Portability (MNP)

The MNP product delivers details about the current Service Provider responsible for the queried phone number, while considering Number Portability. It gathers Number Portability data from multiple sources.

Whether or not the number has been ported, or the country supports Number Portability, the MNP product will still generate a routing result. For numbers that haven't been ported or belong to countries without portability, ownership information is derived from Numbering Range Information.

Before resolving the MNP query, the number is validated through the NRI database. If the number is found to be invalid, a reason code will be provided explaining the failure.

MNP is commonly used to optimize the routing of SMS and voice calls, as identifying the network serving the B-number in advance can lead to cost savings and improved quality in traffic termination.

The example below demonstrates a successful MNP query and its corresponding response.

curl "https://api.num-id.com/query/351923XXXXXX?service=mnp"

# Response (HTTP 201)
{
  "tn":  "351923******",
  "pdi": true,
  "pi":  true,
  "od":  "86200081",
  "oc":  "PT",
  "on":  "VODAFONE PORTUGAL - COMUNICACOES PESSOAIS (01)",
  "nt":  "mobile",
  "mcc": "268",
  "mnc": "01",
  "rc":  "1-00"
}

If the MNP query is unable to return routing information, an appropriate reason code will be provided, explaining the cause of the failure. For customers with the 'Fallback to NRI' option enabled, routing information derived from NRI data will be returned instead. In this case, the pdi value will be set to false, and a relevant reason code will also be included.

5.3. Home Location Register (HLR)

The HLR product provides real-time information about the current Service Provider and the live status of the queried mobile number. It uses live network sources (e.g., HLR or MNO APIs), so it can indicate whether the number is valid and reachable at the time of the query.

Whether or not the number has been ported, the HLR product returns a routing result based on live sources. For numbers or destinations where a live response is not available, ownership and routing can be derived from Numbering Range Information (NRI) when the customer has this fallback enabled.

Before resolving the HLR query, the number is validated against NRI. If the number is invalid, a release code will be returned explaining the failure. When a live response is successful, the service also returns the number status field (sn), e.g. success, unknown subscriber or absent subscriber.

HLR is commonly used to optimize SMS and voice routing and to validate destinations in real time, improving deliverability and reducing costs by avoiding traffic to unreachable numbers.

The example below demonstrates a successful HLR query and its corresponding response.

curl "https://api.num-id.com/query/351923XXXXXX?service=hlr"

# Response (HTTP 201)
{
  "tn":  "351923******",
  "oc":  "PT",
  "mcc": "268",
  "mnc": "01",
  "pdi": true,
  "pi":  true,
  "nt":  "mobile",
  "vn":  "000",
  "sn":  "000",
  "rc":  "1-00"
}

If the HLR query cannot return live routing/status information, an appropriate release code will explain the cause. For customers with the 'Fallback to NRI' option enabled, routing information derived from NRI will be returned instead; in that case, pdi will be set to false and the response will not include a live status.