Access methods

You can run the same Number Lookup in four ways. Each method returns a different level of detail, so choose one based on how you integrate and what data you need:

Web interface [#over-the-web-interface]

To run a lookup from the web interface (Broadcast):

1. Log in to the web interface.
2. Go to Broadcast > Broadcasts, then select Create Broadcast.
3. Select Number Lookup as the supporting feature.
4. Add the recipients to check. Paste a list of numbers, select destinations from People or Customer Profiles, or upload a file.
5. Select Continue to preview to validate the numbers.
6. Create the report, or use Analyze to build and download it.

LEARN MORE

For a detailed report, Analyze can produce a per-number output that includes the operator, country, portability, and roaming results. For the full list of columns, see Number Lookup detailed report columns.

REST API [#over-the-api]

Call the Number Lookup API with the list of numbers to check. The API reference is the source of truth for request and response formats, the returned fields, and the full status list.

The API supports two modes:

• Synchronous: The lookup completes before the API responds, so the HTTP response contains the result directly. Use this mode when your code proceeds only once the result is available.
• Asynchronous: The API responds immediately, then sends the result to a notifyUrl you provide when the lookup completes. Use this mode for bulk or non-blocking workflows.

The API provides these endpoints:

Phone numbers must be in international format (for example, 41793026727). Send the numbers to check in the to array:

Example: Request

Each result reports the network, portability, roaming, and a status for one number:

Example: Response

This example shows one simple case. Ported, roaming, and error responses return additional fields. The fields you receive depend on your package. To change your package, contact your account manager or Support.

LEARN MORE

See the Number Lookup API reference for the ported, roaming, and error responses, all fields, and the full status and error list.

SMPP [#over-smpp]

If you already connect over SMPP, you can request a lookup on the same connection instead of calling the REST API. This suits clients that are bound over SMPP and want lookups without a separate HTTP integration. For the SMPP protocol itself (binding, PDUs, sessions), see the SMPP specification.

To request a lookup over SMPP:

1. Bind with your default system_id and password, setting system_type = HLR in the bind PDU.
2. Send a SubmitSM PDU with destAddress set to the number to check. The lookup ignores other parameters, such as srcAddress and TON/NPI.
3. The Number Lookup subsystem replies with a SubmitSMResp containing the message_id reference.
4. When the lookup finishes, you receive a DeliverSM PDU. It carries the IMSI for the destination address when it is available, or an error code on failure. It can also include additional fields.

The DeliverSM PDU returns the result fields as these TLVs:

In addition to the Number Lookup custom TLVs in the preceding table, the DeliverSM PDU includes the standard SMPP delivery receipt TLVs:

• receipted_message_id (0x001E, 30): The message_id from the SubmitSMResp. Use it to correlate the result with the request.
• message_state (0x0427, 1063): The overall status of the lookup.
• network_error_code (0x0423, 1059): The network error code, if the lookup failed.

Your existing SMPP delivery receipt handler correlates Number Lookup results through receipted_message_id, so you do not need custom correlation logic.

Example: Successful lookup

Example: Failed lookup

ENUM [#over-enum]

For high-volume, low-latency lookups, query Number Lookup over DNS with ENUM. For the query and response formats, see the ENUM integration manual.