Nexmo Number Insight API

Name: Number Insight API
Brand: Number Insight API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentData EnrichmentContact EnrichmentapiKey4 Endpoints

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.

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with Number Insight API

Explore with Jentic

View OpenAPI Document

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.

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

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.

Intent-based discovery

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.

Time to first call

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.

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

Yes. Because Jentic One is self-hosted, your own rules decide which Number Insight operations the agent may call, and it scopes by operation since every tier takes the phone number as a query parameter and differs only by the lookup path. You can allow just the Basic /basic/{format} and Standard /standard/{format} lookups for validation, carrier, and line-type checks while leaving out the Advanced /advanced/{format} and async /advanced/async/{format} reachability and roaming lookups. Anything beyond the operations you permit does not run, and your Nexmo api_key and api_secret stay encrypted in your own instance and are injected only at execution time.