canonical: https://jentic.com/apis/nexmo.com/nexmo-number-insight-api

# Nexmo Number Insight API

The Nexmo Number Insight API delivers real-time intelligence about phone numbers, including validity, line type, carrier, country, roaming status, and whether the number is currently reachable. It comes in three tiers - Basic for formatting and country lookup, Standard for carrier and line-type data, and Advanced for live network reachability and roaming detection - plus an asynchronous variant for high-volume Advanced lookups. Applications use it to validate sign-ups, score fraud risk, and choose the right channel before sending an SMS or voice call.

## For AI agents

Look up validity, carrier, line type, country, and roaming status for any international phone number across four tiers of enrichment.

## Scope

Does not send messages, place calls, or run KYC document checks - use for phone number validation and enrichment only.

## Capabilities

- Validate that a phone number is correctly formatted and dialable in E.164 form
- Identify the carrier and line type (mobile, landline, VoIP) for a given MSISDN
- Detect whether a mobile number is currently roaming and the visited country
- Run advanced lookups asynchronously via webhook callback for high-volume traffic
- Score fraud risk on a phone number before completing a sign-up or transaction

## Use cases

### Sign-up phone validation

When a user enters a phone number during sign-up, the application calls the Basic or Standard tier to confirm the number is correctly formatted, dialable, and tied to a real carrier before sending a verification SMS. This prevents wasted SMS spend on malformed or fictitious numbers and reduces friction for legitimate users.

Example prompt: GET /basic/json with number=+447700900000 and country=GB and return the validated international format

### Channel selection before send

Messaging platforms call the Standard tier to decide whether to deliver a notification by SMS or voice. If the line type comes back as landline, the platform falls back to a voice call automatically; if it is VoIP, it can flag the number for additional fraud checks before sending anything.

Example prompt: GET /standard/json for the recipient number and route to voice if current_carrier.network_type is landline

### Fraud scoring with reachability

Risk teams call the Advanced tier on high-value transactions to confirm the number is live on the network and not roaming in an unexpected country. The reachability and roaming fields, combined with the ported flag, give a strong signal for blocking SIM-swap fraud and traveller-fraud patterns before a transaction is approved.

Example prompt: GET /advanced/json for the cardholder number and reject the transaction if roaming.status is 'roaming' and roaming.network_code does not match the cardholder country

### High-volume async enrichment

Marketing teams enrich large CRM segments by submitting numbers to the asynchronous Advanced endpoint. Nexmo processes the lookups out-of-band and POSTs each result to a webhook URL, which lets the team enrich tens of thousands of numbers without holding open an HTTP request per record.

Example prompt: GET /advanced/async/json with number, country, and callback URL for each row in the CRM export

### AI agent number validation via Jentic

An AI assistant collecting a phone number during a chat-driven sign-up can call Number Insight through Jentic to validate the number before triggering a verification SMS. Jentic exposes the operation by intent, injects the apiKey and apiSecret, and returns the structured insight payload directly to the agent.

Example prompt: Search Jentic for 'validate a phone number', load /basic/json, and execute with number=NUMBER and country=COUNTRY

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /basic/{format} | Basic number formatting and country lookup |
| GET | /standard/{format} | Add carrier and line type data |
| GET | /advanced/{format} | Add reachability and roaming detection |
| GET | /advanced/async/{format} | Asynchronous Advanced lookup via webhook |

## Key resources

- **Basic Insight** — GET /basic/{format} returns formatting and country information for a number.
- **Standard Insight** — GET /standard/{format} adds carrier, line type, and ported status.
- **Advanced Insight** — GET /advanced/{format} adds reachability, roaming, and risk score.
- **Advanced Async** — GET /advanced/async/{format} delivers the same Advanced data via webhook callback.

## Why Jentic

- **Setup:** Wiring the Number Insight API by hand means appending your api_key and api_secret to every query string, choosing the right basic, standard, or advanced tier, and targeting the api.nexmo.com/ni host. Through Jentic you install once, import the Number Insight API from the API Directory, store the api_key and api_secret once, and your agent calls it.
- **Permission scoping:** The Number Insight API takes the phone number as a query parameter and varies only by lookup tier in the path, so scoping is by operation rather than by resource: limit the agent to the operations it needs, such as a basic or standard number lookup. You can leave out the advanced tier unless you add it, and nothing beyond the allowed lookups runs.
- **Credential handling:** Your Nexmo api_key and api_secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check if a phone number is valid' or 'detect roaming on a mobile number', and Jentic returns the matching insight tier with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio Lookup v2** — Twilio's equivalent phone number intelligence service with line type and SIM-swap data packages.
- **Numverify** — Lower-cost phone validation API focused on formatting, country, and carrier - no live reachability.
- **Nexmo SMS API** — The SMS API is the natural next call once Number Insight confirms the number is mobile and reachable.
- **Nexmo Verify API** — Verify orchestrates the full 2FA flow on top of validated numbers from Number Insight.

## FAQ

### What authentication does the Nexmo Number Insight API use?

The API uses apiKey and apiSecret passed as query parameters on each request. Through Jentic those credentials live encrypted in the vault and the agent only ever sees a scoped token, never the raw api_secret.

### Can I detect roaming and SIM-swap with Number Insight?

Yes - but only with the Advanced tier. GET /advanced/json returns roaming.status, roaming.network_code, and the ported flag, which together cover the most common SIM-swap and traveller-fraud signals. Basic and Standard tiers do not include reachability.

### What are the rate limits for the Number Insight API?

Vonage does not encode a rate limit in the OpenAPI spec, but the asynchronous Advanced endpoint exists specifically to handle high-volume enrichment. For batch jobs use /advanced/async/json with a callback URL rather than parallelising synchronous calls.

### How do I run a Standard insight lookup through Jentic?

Run pip install jentic, search for 'lookup phone carrier and line type', and Jentic returns GET /standard/{format}. Execute with number and country parameters and Jentic returns the carrier, network_type, and ported fields directly.

### What's the difference between the three insight tiers?

Basic returns formatting and country only. Standard adds current_carrier and line type (mobile, landline, mobile_premium, voip). Advanced adds reachability, roaming detail, and a risk score, and is the only tier that hits the live mobile network.

### Is the Number Insight API free?

No. Each tier is priced per lookup with Basic the cheapest and Advanced the most expensive, and pricing varies by destination country. Use the Basic tier for cheap top-of-funnel validation and reserve Advanced calls for high-value risk decisions.

### Can I limit what my agent is allowed to do with the Nexmo Number Insight API?

Yes. Because you run Jentic One yourself, your own rules decide which Number Insight operations and credentials the agent may use, and scoping here is by operation rather than by resource. You can allow only the tiers the agent actually needs, such as the Basic lookup (GET /basic/{format}) or the Standard carrier and line-type lookup (GET /standard/{format}), while withholding the Advanced (GET /advanced/{format}) and async endpoints so reachability and roaming calls never run. Your stored Nexmo api_key and api_secret are injected only for the operations you permit, so nothing beyond the allowed lookups executes.