canonical: https://jentic.com/apis/nexmo.com/nexmo-numbers-api

# Nexmo Numbers API

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.

## For AI agents

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

## Scope

Does not send messages, place calls, or port existing numbers - use for virtual number provisioning and configuration only.

## Capabilities

- 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
- List every virtual number currently owned by the account with status and capability

## Use cases

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

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

## Key endpoints

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

## Key resources

- **Number search** — GET /number/search lists available inventory by country and feature.
- **Number buy** — POST /number/buy purchases a specific MSISDN.
- **Number update** — POST /number/update changes inbound webhook configuration on an owned number.
- **Number cancel** — POST /number/cancel releases a number and stops the monthly rental.
- **Account numbers** — GET /account/numbers lists every number currently owned by the account.

## Why Jentic

- **Setup:** Wiring the Numbers API by hand means setting the X-API-Key and apiSecret headers on every request and targeting the rest.nexmo.com host for search and provisioning calls. Through Jentic you install once, import the Numbers API from the API Directory, store the API key and secret once, and your agent calls it.
- **Permission scoping:** The Numbers API carries the number and country in the request body or query, so scoping is by operation rather than by resource: limit the agent to the operations it needs, such as searching available numbers and updating configuration. You choose the operations it may call, so destructive ones like buying or cancelling a number are not included unless you add them.
- **Credential handling:** Your Nexmo API key and 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 'buy a virtual phone number for SMS' or 'list my Nexmo numbers', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio Phone Numbers v2** — Twilio's equivalent number provisioning API with the same search-buy-configure flow.
- **Nexmo SMS API** — The SMS API is the primary consumer of numbers purchased through the Numbers API.
- **Nexmo Voice API** — Numbers with the VOICE feature plug into the Voice API for inbound and outbound calling.

## FAQ

### 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.

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

Yes. Because your Jentic One instance is self-hosted, your own rules decide which operations and credentials the agent can use, and the Numbers API scopes by operation rather than by resource. You can allow the agent only the calls it needs, such as GET /number/search and POST /number/update to reconfigure webhooks, while withholding the destructive POST /number/buy and POST /number/cancel operations unless you explicitly add them. Your Nexmo API key and secret stay stored and injected at execution time, so the agent runs only the operations you permit and never sees the raw secret.