Nexmo Account API
Browse all Nexmo APIs★ Only Publicly Available OpenAPI DocumentFinanceBankingbasic8 EndpointsREST
For Agents
Read Vonage account balance, top up credit, manage API secrets, and configure default SMS and DLR callback URLs across a Vonage account.
Use for: I want to check my Vonage account balance, Top up my Vonage credit from the linked auto-reload account, Rotate the API secret on my Vonage API key, List all secrets attached to my Vonage account
Not supported: Does not handle SMS sending, voice calls, number provisioning, or verification flows - use for Vonage account balance, callback configuration, and API secret management only.
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.
Install Jentic One Beta
Connect the Account API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Account API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnexmo.com%2Fvonage-account" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnexmo.com%2Fvonage-account" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Account API.
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
Patterns agents use Account API for, with concrete tasks.
★ 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.
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.
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.
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.
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
8 endpoints — the vonage account api (account) lets you manage a vonage (formerly nexmo) communications account programmatically.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Account API through Jentic.
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.
GET STARTED