canonical: https://jentic.com/apis/nexmo.com/nexmo-numbers # 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 you run Jentic One yourself, you decide which operations your agent may call, and scoping here is by operation rather than by resource. You can allow read-and-configure operations such as searching available numbers with GET `/number/search` and updating webhook configuration with POST `/number/update`, while withholding destructive ones like POST `/number/buy` and POST `/number/cancel` unless you explicitly add them. The Nexmo API key and secret stay stored by your own instance and are injected only at execution time, so the agent can act just within the operation set your rules permit.