Nexmo Number Insight API
Browse all Nexmo APIs★ Only Publicly Available OpenAPI DocumentData EnrichmentContact EnrichmentapiKey4 EndpointsREST
For Agents
Look up validity, carrier, line type, country, and roaming status for any international phone number across four tiers of enrichment.
Use for: I want to check if a phone number is valid before sending an SMS, Look up the carrier for a UK mobile number, Find out whether this number is a landline or a mobile, Check whether a number is currently roaming abroad
Not supported: Does not send messages, place calls, or run KYC document checks — use for phone number validation and enrichment only.
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.
Install Jentic One Beta
Connect the Number Insight API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Number Insight API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Number Insight API.
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
Patterns agents use Number Insight API for, with concrete tasks.
★ 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.
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.
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.
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.
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.
Search Jentic for 'validate a phone number', load /basic/json, and execute with number=NUMBER and country=COUNTRY
Key Endpoints
4 endpoints — 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.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Nexmo apiKey and apiSecret are stored encrypted in the Jentic vault. Agents receive scoped access tokens; the raw secret never enters the agent's context window or logs.
Intent-based discovery
Agents search Jentic by intent (e.g. '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.
Time to first call
Direct integration: 1-2 days for auth, async webhook handling, and tier selection logic. Through Jentic: under 30 minutes — search, load, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Number Insight API through Jentic.
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.
GET STARTED