A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Vonage API is how an app or AI agent reaches a phone network: sending an SMS or WhatsApp message, placing a voice call, verifying a user with a one-time code, or looking up a number. Access comes from an account key and secret for some APIs and a token signed by an application's private key for others, and since Vonage has no per-endpoint scopes, whatever holds a valid credential can do everything that credential allows. Each Vonage product is its own API, and events like an inbound message are pushed to webhook URLs set per application.
How an app or AI agent connects to Vonage determines what it can reach. Some APIs answer with an account key and secret, others with a token signed by an application's private key, and a hosted server exposes Vonage tools to agents, each governed by the credential behind it.
Vonage is a set of separate REST APIs rather than one. Messages, Voice, and Verify answer at api.nexmo.com, while the SMS, Number Insight, Numbers, and Account APIs answer at rest.nexmo.com. Each API has its own path version, its own base address, and its own accepted credentials.
Vonage POSTs events to webhook URLs registered on an application or number, such as an inbound message, a message status update, or a call answer or completion event. There is no central event feed, so the events delivered depend on which URLs are configured.
Vonage's first-party Tooling MCP server, also called the API Bindings server, exposes Vonage APIs to AI agents through the Model Context Protocol. It runs locally over standard input and output through the npx package @vonage/vonage-mcp-server-api-bindings, authenticating with the VONAGE_API_KEY and VONAGE_API_SECRET environment variables, and covers tasks like checking the balance, sending SMS, and managing applications.
Vonage's first-party Documentation MCP server gives an agent access to Vonage API documentation, code snippets, and tutorials over the Model Context Protocol, not to live account data. It is a remote server at https://documentation-mcp.vonage.dev/mcp.
The account API key and secret authenticate most APIs through HTTP Basic auth, base64-encoded and joined by a colon. They work for the SMS, Number Insight, Numbers, and Account APIs, and for SMS and MMS over the Messages API, and grant the full account, since Vonage has no per-resource scopes on the key.
Voice and the WhatsApp, Viber, RCS, and Messenger channels of the Messages API authenticate with a JSON Web Token signed by an application's private key. The application's linked capabilities define what the token can do, since there is no scope on the token itself.
The legacy SMS API can authenticate a request with a signature instead of the plain secret, sending api_key, a sig hash, and a timestamp, so the secret never travels in the request. The signature is computed from the request parameters and a signing secret.
The Vonage platform is split into separate APIs an agent can act on, such as messaging, voice calls, identity verification, number lookup, and number management. Each has its own methods and its own base address, and writes in some send real messages, place real calls, or spend account credit.
Send a message across SMS, MMS, WhatsApp, Viber, RCS, or Facebook Messenger through one endpoint, and update the status of a sent message.
Send an outbound SMS through the original single-channel SMS API, which predates the unified Messages API.
Create an outbound call, list and read calls, transfer an in-progress call to new instructions, and play audio or text-to-speech into a call.
Start a verification, check a user-supplied code, advance to the next channel, and cancel a request, through the newer Verify v2 API.
Look up basic, standard, or advanced information about a phone number, such as its format, carrier, and validity.
List the numbers an account owns, search for available numbers, buy a number, cancel a number, and change a number's behaviour.
Read the account balance, update account-level webhook settings, and list, create, or revoke the API secrets on an account.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MessagesSend a message across SMS, MMS, WhatsApp, Viber, RCS, or Facebook Messenger through one endpoint, and update the status of a sent message.2 | ||||||
| POST | /v1/messages | Send a message over SMS, MMS, WhatsApp, Viber, RCS, or Facebook Messenger, chosen by the channel field in the body. | write | Messages: send | Current | |
Vonage has no per-endpoint OAuth scopes; access is the credential itself. Basic auth with the API key and secret works for SMS and MMS, while WhatsApp, Viber, RCS, and Messenger need a JWT signed by an application's private key. Returns a message_uuid. Acts onmessage Permission (capability) Messages: sendVersionAvailable since the API’s base version Webhook event message-statusRate limit75 requests per second per API key SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/messages/{message_uuid} | Update a sent message, such as marking a WhatsApp message as read or revoking an RCS message. | write | Messages: send | Current | |
JWT authentication only, signed by an application's private key. Acts onmessage Permission (capability) Messages: sendVersionAvailable since the API’s base version Webhook eventNone Rate limit75 requests per second per API key SourceOfficial documentation ↗ | ||||||
SMS (legacy)Send an outbound SMS through the original single-channel SMS API, which predates the unified Messages API.1 | ||||||
| POST | /sms/{format} | Send an outbound SMS through the legacy single-channel SMS API, with format being json or xml. | write | SMS: send | Current | |
Answers at rest.nexmo.com, not the api.nexmo.com host. Authenticates with the API key and secret, or with a signed request using api_key, sig, and timestamp. Newer integrations use the Messages API instead. Acts onsms Permission (capability) SMS: sendVersionAvailable since the API’s base version Webhook eventNone Rate limit30 requests per second per API key by default SourceOfficial documentation ↗ | ||||||
VoiceCreate an outbound call, list and read calls, transfer an in-progress call to new instructions, and play audio or text-to-speech into a call.6 | ||||||
| POST | /v1/calls | Create an outbound call to one or more destinations, controlled by a Call Control Object or an answer URL. | write | Voice: write | Current | |
JWT signed by a Voice application's private key. Limited to 3 outbound calls created per second across all voice products. Acts oncall Permission (capability) Voice: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit3 calls per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/calls | List calls on the account, with filters for status, date range, and conversation. | read | Voice: read | Current | |
JWT signed by a Voice application's private key. Counts toward the 15 requests per second non-create voice limit. Acts oncall Permission (capability) Voice: readVersionAvailable since the API’s base version Webhook eventNone Rate limit15 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/calls/{uuid} | Get the details of a single call by its UUID. | read | Voice: read | Current | |
JWT signed by a Voice application's private key. Counts toward the 15 requests per second non-create voice limit. Acts oncall Permission (capability) Voice: readVersionAvailable since the API’s base version Webhook eventNone Rate limit15 requests per second SourceOfficial documentation ↗ | ||||||
| PUT | /v1/calls/{uuid} | Modify an in-progress call, such as transferring it to new Call Control Object instructions, hanging it up, muting, or unmuting. | write | Voice: write | Current | |
JWT signed by a Voice application's private key. Counts toward the 15 requests per second non-create voice limit. Acts oncall Permission (capability) Voice: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit15 requests per second SourceOfficial documentation ↗ | ||||||
| PUT | /v1/calls/{uuid}/talk | Play synthesised text-to-speech into an in-progress call. | write | Voice: write | Current | |
JWT signed by a Voice application's private key. Counts toward the 15 requests per second non-create voice limit. Acts oncall Permission (capability) Voice: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit15 requests per second SourceOfficial documentation ↗ | ||||||
| PUT | /v1/calls/{uuid}/stream | Stream an audio file into an in-progress call. | write | Voice: write | Current | |
JWT signed by a Voice application's private key. Counts toward the 15 requests per second non-create voice limit. Acts oncall Permission (capability) Voice: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit15 requests per second SourceOfficial documentation ↗ | ||||||
VerifyStart a verification, check a user-supplied code, advance to the next channel, and cancel a request, through the newer Verify v2 API.5 | ||||||
| POST | /v2/verify | Start a verification, sending a code to a user across one or more channels defined by a workflow, such as SMS then voice. | write | Verify: write | Current | |
Verify v2 accepts a JWT or Basic auth with the API key and secret. Returns a request_id used to check the code. The original Verify API uses POST /verify and POST /verify/check instead. Acts onverification Permission (capability) Verify: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/verify/{request_id} | Check a user-supplied code against an active verification request. | write | Verify: write | Current | |
A JWT or Basic auth with the API key and secret. A wrong code returns 401, an expired or already-verified request returns 409 or 410. Acts onverification Permission (capability) Verify: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/verify/{request_id}/next_workflow | Advance a verification to the next channel in its workflow, such as moving from SMS to voice. | write | Verify: write | Current | |
A JWT or Basic auth with the API key and secret. Acts onverification Permission (capability) Verify: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/verify/{request_id} | Cancel an in-progress verification request before it completes. | write | Verify: write | Current | |
A JWT or Basic auth with the API key and secret. Valid from 30 seconds after the request starts and before the second workflow event. Acts onverification Permission (capability) Verify: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/verify/templates | List the custom verification templates on the account. | read | Verify: read | Current | |
A JWT or Basic auth with the API key and secret. Acts ontemplate Permission (capability) Verify: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Number InsightLook up basic, standard, or advanced information about a phone number, such as its format, carrier, and validity.3 | ||||||
| GET | /ni/basic/{format} | Return basic insight on a number, including its international and national format and country. | read | Number Insight: read | Current | |
Answers at rest.nexmo.com with Basic auth using the API key and secret. The Number Insight API is being sunset on 4 February 2027, with Identity Insights as the successor. Acts onnumber insight Permission (capability) Number Insight: readVersionSunset 2027-02-04 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /ni/standard/{format} | Return standard insight on a number, adding the current carrier and whether the number has been ported. | read | Number Insight: read | Current | |
A billable lookup. Answers at rest.nexmo.com with Basic auth. Sunset on 4 February 2027 in favour of Identity Insights. Acts onnumber insight Permission (capability) Number Insight: readVersionSunset 2027-02-04 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /ni/advanced/{format} | Return advanced insight on a number synchronously, adding roaming status, reachability, and validity checks. | read | Number Insight: read | Current | |
A billable lookup. Answers at rest.nexmo.com with Basic auth. An asynchronous variant at /ni/advanced/async returns results to a callback URL. Sunset on 4 February 2027. Acts onnumber insight Permission (capability) Number Insight: readVersionSunset 2027-02-04 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NumbersList the numbers an account owns, search for available numbers, buy a number, cancel a number, and change a number's behaviour.5 | ||||||
| GET | /account/numbers | List the inbound numbers the account owns, with filters and pagination. | read | Numbers: read | Current | |
Answers at rest.nexmo.com with Basic auth using the API key and secret. This endpoint is limited to 1 request per second. Acts onnumber Permission (capability) Numbers: readVersionAvailable since the API’s base version Webhook eventNone Rate limit1 request per second SourceOfficial documentation ↗ | ||||||
| GET | /number/search | Search for inbound numbers available to buy in a chosen country. | read | Numbers: read | Current | |
Answers at rest.nexmo.com with Basic auth. The Numbers API is limited to 3 requests per second. Acts onnumber Permission (capability) Numbers: readVersionAvailable since the API’s base version Webhook eventNone Rate limit3 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /number/buy | Buy a specific inbound number for the account. | write | Numbers: write | Current | |
Answers at rest.nexmo.com with Basic auth. Starts a recurring charge for the number. Acts onnumber Permission (capability) Numbers: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit3 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /number/cancel | Cancel the subscription for an inbound number the account owns. | write | Numbers: write | Current | |
Answers at rest.nexmo.com with Basic auth. Releases the number, which cannot be guaranteed back. Acts onnumber Permission (capability) Numbers: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit3 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /number/update | Change the behaviour of an owned number, such as its inbound webhook URLs or linked application. | write | Numbers: write | Current | |
Answers at rest.nexmo.com with Basic auth. Acts onnumber Permission (capability) Numbers: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit3 requests per second SourceOfficial documentation ↗ | ||||||
AccountRead the account balance, update account-level webhook settings, and list, create, or revoke the API secrets on an account.4 | ||||||
| GET | /account/get-balance | Read the current account balance in euros and the auto-reload status. | read | Account: read | Current | |
Answers at rest.nexmo.com with Basic auth using the API key and secret. Acts onaccount Permission (capability) Account: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /account/settings | Update the account-level default webhook URLs for inbound SMS and delivery receipts. | write | Account: write | Current | |
Answers at rest.nexmo.com with Basic auth. Acts onaccount Permission (capability) Account: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/{api_key}/secrets | List the API secrets configured on an account. | read | Account: read | Current | |
Answers at api.nexmo.com with Basic auth. The secret value itself is shown only when a secret is created. Acts onsecret Permission (capability) Account: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/{api_key}/secrets | Create a new API secret on an account. | write | Account: write | Current | |
Answers at api.nexmo.com with Basic auth. A secret must be 8 to 25 characters with an uppercase letter, a lowercase letter, and a digit. The new secret authenticates calls on the account. Acts onsecret Permission (capability) Account: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Vonage can notify an app or AI agent when something happens, like an inbound message arriving or a call changing state, instead of the app repeatedly asking. The events delivered depend on the application and the webhook URLs registered on it, since there is no central event feed.
| Event | What it signals | Triggered by |
|---|---|---|
inbound message | Fires when a message is received on a Vonage number or channel, carrying the channel, sender, recipient, timestamp, and content. Vonage POSTs it to the inbound URL set on the application. | In-app only |
message status | Fires when a sent message changes state, such as submitted, delivered, read, rejected, or undeliverable, and includes any error detail and usage pricing. Vonage POSTs it to the status URL set on the application. | /v1/messages |
call event | Fires as a call moves through its lifecycle, such as started, ringing, answered, and completed, sent to the event URL on the Voice application or the create-call request. | /v1/calls |
Vonage limits how fast an app or AI agent can call, and the limit is set per API rather than across the whole platform. Each API publishes its own ceiling, like a few calls per second for voice and a higher rate for messaging.
Vonage sets a rate limit per API, not one ceiling across the platform. The Messages API allows 75 requests per second per API key by default, raised case by case through an account manager, while the legacy SMS API defaults to 30 requests per second per key. Voice allows 3 outbound calls created per second, shared across all voice products, plus 15 requests per second for other voice calls like listing and modifying. The Numbers API allows 3 requests per second, with the list-owned-numbers endpoint held to 1 per second. Going over any limit returns HTTP 429, and channel or network providers may apply their own stricter throughput on top.
List endpoints differ by API. Voice lists calls with page_size and record_index plus an order field, and Verify v2 lists templates with page and page_size. The legacy SMS, Number Insight, and Account APIs are mostly single-object lookups rather than paged lists, so pagination applies only where a list is returned.
Per-message size depends on the channel: a single SMS segment is 160 GSM-7 characters or 70 unicode characters, and longer messages are split into concatenated segments and billed per segment. Channels such as WhatsApp and MMS set their own media and length limits. An API secret is 8 to 25 characters.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The credentials are missing or invalid: a wrong API key or secret, a JWT that does not verify, or for Verify a code that does not match. | Send valid credentials for that API, the key and secret or a JWT signed by the right application key. For Verify, treat 401 on a check as a wrong code. |
| 402 | Out of credit | The account balance is too low to cover the request, returned in RFC 7807 form with type, title, detail, and instance fields. | Top up the account balance, then resend the request. |
| 422 | Unprocessable Entity | The request was understood but a field is invalid, such as a malformed number or an unsupported channel option. Newer APIs return the detail in RFC 7807 form. | Read the title and detail in the problem response, correct the named field, and resend. |
| 429 | Too Many Requests | The per-API rate limit was exceeded, such as more than 3 calls per second on Voice or above the per-key throughput on Messages. | Back off and retry with exponential backoff, and smooth the request rate to stay under that API's limit. |
| 500 | Internal Server Error | An error on Vonage's side. It is uncommon. | Retry with backoff, and contact Vonage support if it persists. |
Vonage versions each API independently in its path, so the Messages and Voice APIs sit at v1, Verify has both an original release and a newer v2, and Number Insight and the legacy SMS API carry no version segment.
The Messages and Voice APIs sit at path version v1 on api.nexmo.com. The Messages API unifies SMS, MMS, WhatsApp, Viber, RCS, and Messenger behind one send endpoint, and the Voice API controls live calls through Call Control Objects. Both are the current build path for new messaging and voice integrations.
Verify v2 at /v2/verify adds multi-channel workflows, such as SMS then voice then WhatsApp, custom templates, and silent authentication, over the original Verify API. The original Verify API at /verify remains available for existing integrations.
Vonage will sunset the Number Insight API on 4 February 2027 and recommends migrating to the Identity Insights API, which consolidates number datasets such as formatting, carrier, SIM-swap, and subscriber match into a single request. A transition guide documents the differences.
An integration pins to a specific API and its path version, and migrates when an API publishes a successor.
Vonage API reference ↗Bollard AI sits between a team's AI agents and Vonage. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.