Numbers API

Name: Numbers API API
Brand: Numbers API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentCommunicationsVoice TelephonyapiKey5 EndpointsREST

For Agents

Search Vonage's virtual number inventory, buy and cancel numbers, and configure their inbound SMS and voice webhooks programmatically.

Quickstart

Get started with Numbers API in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"buy a virtual phone number for sms"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with Numbers API API.

Search Vonage's inventory for available virtual numbers by country and feature

Buy a virtual number in a specific country and assign it to your account

Update an owned number's inbound SMS and voice webhook configuration

Cancel a previously purchased number to stop monthly rental charges

GET STARTED

Start building with Numbers API API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Numbers API, keeping it validated and agent-ready.

The Nexmo Numbers API lets developers search, buy, configure, and cancel virtual phone numbers across the countries Vonage supports. Each number can be wired to receive SMS or voice traffic and routed to a webhook, an application, or a SIP endpoint. The API exposes five operations covering inventory search, purchase, update, cancellation, and listing of currently owned numbers, and is the foundation that the SMS, Voice, and Messages APIs sit on top of.

Use Cases

Patterns agents use Numbers API API for, with concrete tasks.

★ Provisioning a new SMS sender

When an application needs a dedicated long-code or toll-free sender, the team calls /number/search to find available inventory in the target country, /number/buy to purchase it, and /number/update to wire the inbound webhook to their application. The whole provisioning flow takes three API calls and replaces a manual portal-based purchase.

Call GET /number/search?country=US&features=SMS, pick the first MSISDN, then POST /number/buy with country and msisdn

Inbound webhook reconfiguration

When a service migrates to a new domain or splits inbound SMS and voice handlers across services, operators call /number/update for each owned number to point moHttpUrl and voiceCallbackValue at the new endpoints. Doing this through the API rather than the portal keeps the configuration in version control and reproducible across environments.

POST /number/update with country, msisdn, and the new moHttpUrl pointing at https://api.example.com/inbound-sms

Number portfolio audit

Finance and operations teams call /account/numbers to list every number the account holds, including capabilities, country, and current webhook target. The output drives quarterly audits to cancel unused numbers, confirm two-region failover coverage, and reconcile the bill against the active inventory.

GET /account/numbers and group the response by country and feature to produce an inventory report

AI agent number provisioning via Jentic

An AI agent that orchestrates messaging campaigns can request a fresh sender programmatically through Jentic. The agent calls the search operation, picks an MSISDN that supports SMS in the target country, and executes the buy operation, all without ever holding the raw apiKey/apiSecret pair.

Search Jentic for 'buy a virtual phone number for sms', load /number/buy, and execute with country=US and the chosen msisdn

Key Endpoints

5 endpoints — the nexmo numbers api lets developers search, buy, configure, and cancel virtual phone numbers across the countries vonage supports.

METHOD

PATH

DESCRIPTION

GET

/account/numbers

List numbers owned by the account

GET

/number/search

Search available numbers in inventory

POST

/number/buy

Purchase a virtual number

POST

/number/update

Update webhook configuration on an owned number

POST

/number/cancel

Release a number and stop billing

GET

/account/numbers

List numbers owned by the account

GET

/number/search

Search available numbers in inventory

POST

/number/buy

Purchase a virtual number

POST

/number/update

Update webhook configuration on an owned number

POST

/number/cancel

Release a number and stop billing

Why though 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 tokens, so the raw secret never enters the agent's prompt or logs.

Intent-based discovery

Agents search Jentic by intent (e.g. 'buy a virtual phone number for sms') and Jentic returns the matching POST /number/buy operation along with its input schema.

Time to first call

Direct integration: 1-2 days to handle search-buy-update flow plus webhook configuration. Through Jentic: under 30 minutes — search, load, execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Alternative

Twilio Phone Numbers v2

Twilio's equivalent number provisioning API with the same search-buy-configure flow.

Choose Twilio Phone Numbers when the messaging stack already runs on Twilio or when Twilio Regulatory Bundles are required.

Complementary

Nexmo SMS API

The SMS API is the primary consumer of numbers purchased through the Numbers API.

Buy a number with the SMS feature, then send messages from it via the Nexmo SMS API.

Complementary

Nexmo Voice API

Numbers with the VOICE feature plug into the Voice API for inbound and outbound calling.

Buy a number with VOICE capability, then attach it to a Voice application to receive inbound calls.

FAQs

Specific to using Numbers API API through Jentic.

What authentication does the Nexmo Numbers API use?

The Numbers API uses apiKey and apiSecret query parameters on every request to rest.nexmo.com. Through Jentic those credentials live in the encrypted vault, so an agent only ever sees a scoped access token and never the raw api_secret.

Can I search and buy a number in a single API call?

No — purchase is a two-step flow on purpose. First call GET /number/search with the country and feature filters, then call POST /number/buy with a specific msisdn from the result. Splitting the steps lets the application show inventory to a user before charging the account.

What are the rate limits for the Numbers API?

Vonage does not encode a numeric rate limit in the OpenAPI spec. The provisioning endpoints are not designed for high concurrency — bulk buys should be serialised, and /account/numbers should be cached rather than polled aggressively.

How do I update an inbound SMS webhook through Jentic?

Run pip install jentic, search for 'update inbound sms webhook for nexmo number', and Jentic returns POST /number/update. Execute with country, msisdn, and moHttpUrl set to your new endpoint, and Jentic returns the updated number record.

Can I get a refund for a number I just bought?

Calling POST /number/cancel stops the monthly rental immediately, but Vonage's commercial terms govern any pro-rata refund and that policy is not exposed via the API. Numbers purchased and cancelled in quick succession should be reconciled against your account's billing rules.

What features can I filter on when searching numbers?

The /number/search endpoint accepts a features query parameter that supports SMS, VOICE, and MMS, plus a type parameter for landline, mobile-lvn, and toll-free. Combine them with country and pattern to narrow inventory to exactly what your application needs.