canonical: https://jentic.com/apis/nexmo.com/vonage-account # Nexmo Account API The Vonage Account API (account) lets you manage a Vonage (formerly Nexmo) communications account programmatically. It exposes balance checks, auto-reload top-ups, default SMS and delivery-receipt callback configuration, registered email sender management, and full lifecycle control over the API secrets attached to each Vonage API key. The 8 endpoints cover the operational surface needed to keep a messaging or voice account funded, configured, and credentialed. ## For AI agents Read Vonage account balance, top up credit, manage API secrets, and configure default SMS and DLR callback URLs across a Vonage account. ## Scope Does not handle SMS sending, voice calls, number provisioning, or verification flows - use for Vonage account balance, callback configuration, and API secret management only. ## Capabilities - Check the current credit balance on a Vonage account before launching a messaging campaign - Top up the Vonage account balance from a stored auto-reload account to keep SMS and voice traffic flowing - Rotate API secrets attached to a Vonage account API key for credential hygiene - Register a verified email sender so transactional notifications land from a trusted address - Update default SMS and Delivery Receipt callback URLs that Vonage will invoke on inbound traffic - Audit which API secrets are active on a given API key and revoke any that are no longer in use ## Use cases ### Pre-flight balance check before bulk SMS Before launching a high-volume SMS campaign, an operations workflow needs to confirm there is enough Vonage credit to cover the send. The Account API exposes GET /account/get-balance which returns the current balance and auto-reload status in a single call, so a pipeline can short-circuit a campaign that would otherwise fail mid-send. Implementation is a few hours including alert wiring. Example prompt: Call GET /account/get-balance and abort the campaign if the returned value is below 50.00 EUR. ### Scheduled API secret rotation Security policy often requires rotating outbound API secrets every 90 days. The Account API exposes POST /accounts/{api_key}/secrets to mint a new secret and DELETE /accounts/{api_key}/secrets/{secret_id} to revoke an old one. A scheduled job can rotate without downtime by creating the new secret first, switching consumers, then revoking the old one. Effort is one afternoon for the cron and audit logging. Example prompt: Create a new secret on api_key abc123, update the credential vault, then delete the previous secret_id once traffic has moved over. ### Configure inbound SMS webhook When standing up a new inbound SMS handler, the account-level callback URL must point at the new endpoint. POST /account/settings accepts a moCallBackUrl and drCallBackUrl that Vonage will invoke for inbound messages and delivery receipts. Setting these once at account scope avoids reconfiguring per-number. Roughly 30 minutes of work. Example prompt: Update moCallBackUrl to https://app.example.com/vonage/sms and drCallBackUrl to https://app.example.com/vonage/dlr. ### Agent-driven account top-up An AI ops agent monitoring messaging spend needs to refill credit when balance dips below a floor. Through Jentic, the agent searches for 'top up vonage account', loads the POST /account/top-up schema, and executes the call with a stored trx reference. The agent never holds the API secret directly - Jentic injects credentials from the vault at execution time. Example prompt: Search Jentic for 'top up vonage account', load the schema, then execute POST /account/top-up with the configured auto-reload trx reference. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /account/get-balance | Get the current account credit balance | | POST | /account/top-up | Top up the account from the linked auto-reload account | | POST | /account/settings | Update default SMS and DLR callback URLs | | GET | /accounts/{api_key}/secrets | List API secrets for a key | | POST | /accounts/{api_key}/secrets | Create a new API secret | | DELETE | /accounts/{api_key}/secrets/{secret_id} | Revoke an API secret | | POST | /account/register-sender | Register an email sender | ## Key resources - **Account** — Read account balance, change default callback settings, and trigger an auto-reload top-up. - **Secrets** — List, create, retrieve, and revoke API secrets attached to a Vonage API key. - **Sender** — Register a verified email sender for use in account notifications. ## Why Jentic - **Setup:** Wiring the Vonage Account API by hand means setting up HTTP Basic auth with your API key and secret, pointing at api.nexmo.com, and managing balance, callback, and secret operations yourself. Through Jentic you install once, import the Account API from the API Directory, store the key and secret once, and your agent calls it. - **Permission scoping:** Scope this agent by operation: limit it to the operations it needs, such as checking the account balance or reading settings, and leave the rest out of the allowed set. You choose the operations it may call, so balance top-up, secret creation, and secret deletion are not included unless you add them. - **Credential handling:** Your Vonage API key and secret are stored once, encrypted, by your own Jentic One instance and injected as the Basic auth header at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'check my Vonage account balance' or 'read account settings', and Jentic returns the matching Account API operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Vonage SMS API** — Vonage's SMS sending API, billed against the same Vonage account. - **Vonage Voice API** — Vonage's voice calling API tied to Vonage applications. - **Vonage Verify API** — Vonage's two-factor authentication and phone verification API. - **Twilio Accounts API** — Twilio's account and subaccount management API. - **SendGrid Account Provisioning API** — SendGrid's account, subuser, and balance management API. ## FAQ ### What authentication does the Vonage Account API use? It uses HTTP Basic authentication with the Vonage API key and API secret. Jentic stores both in the encrypted Jentic One instance and injects them per request, so the agent never sees the raw secret in its context. ### Can I rotate API secrets through the Vonage Account API? Yes. POST /accounts/{api_key}/secrets creates a new secret and DELETE /accounts/{api_key}/secrets/{secret_id} revokes an old one. Vonage allows up to two active secrets per key so you can roll without downtime. ### What are the rate limits for the Vonage Account API? Vonage does not publish a hard request-per-second cap for the Account API in the spec. Account-level operations are typically low frequency; treat balance checks as eventual and avoid polling more than once per minute per key. ### How do I check my Vonage balance through Jentic with the Vonage Account API? Run pip install jentic, then search Jentic for 'check vonage account balance'. Jentic returns the GET /account/get-balance operation, you load its schema, and execute it. Credentials are pulled from your Jentic One instance at call time. ### Can I update the SMS callback URL with the Vonage Account API? Yes. POST /account/settings accepts moCallBackUrl for inbound SMS and drCallBackUrl for delivery receipts. These are account-wide defaults and apply unless overridden at number or application scope. ### Is the Vonage Account API free to use? The endpoints themselves are free; you only pay for the underlying Vonage usage they manage (SMS, voice, verification credit). Top-up amounts are billed against your linked payment method via the auto-reload trx reference. ### Can I limit what my agent is allowed to do with the Vonage Account API? Yes. Because Jentic One is self-hosted, you decide which operations the agent may call, so you can allow only read operations like GET /account/get-balance or POST /account/settings reads and leave the rest out of the allowed set. Sensitive operations such as POST /account/top-up, creating a secret with POST /accounts/{api_key}/secrets, or revoking one with DELETE /accounts/{api_key}/secrets/{secret_id} stay out of reach unless you explicitly add them. The Vonage API key and secret are stored once by your own Jentic One instance and injected at call time, so the agent never handles the raw credentials.