Accounts API
Accounts API
Read your Vezmo accounts from your own systems: accounts and balances, transactions, monthly statements and events. This phase is read only: no key can move money, add a recipient, approve anything or change keys, the team or webhook endpoints.
Vezmo switches the Accounts API on per business. Until it is on, every call answers 403 api_access_not_enabled; ask from Settings › Developers › Accounts API in the dashboard.
Endpoints
POST /oauth/token— swap a key for a 15-minute access token (below).- Accounts and balances:
GET /accounts,GET /accounts/{id},GET /balances(accounts.read). - Transactions:
GET /transactions,GET /transactions/{id}(transactions.read). - Statements:
GET /statements,GET /statements/{id}as JSON, CSV or PDF (statements.read). - Events and webhooks:
GET /events,GET /events/{id}(events.read), and signed webhooks. - Sandbox:
POST /simulations/…with a test key.
Base URL: https://api.vezmo.com/api/v1, for test and live keys alike. The key decides the data. The OpenAPI 3 description of these routes is at https://api.vezmo.com/api/v1/openapi.json, for code generators and API tools.
Access tokens
POST /oauth/token is the OAuth 2.0 client-credentials grant (RFC 6749), so any OAuth library works. Authenticate with the key ID and secret one way: HTTP Basic (client_secret_basic), or client_id and client_secret in the body (client_secret_post). The body is form-encoded or JSON. Each endpoint needs its Accounts API permission on the key (a key holding only them has an ID like vzm_live_ro_… or vzm_test_ro_…).
curl -X POST https://api.vezmo.com/api/v1/oauth/token \
-u "$VEZMO_KEY_ID:$VEZMO_SECRET" \
-d grant_type=client_credentialsAn optional scope (space-separated) narrows the token to some of the key's permissions; the token can then use only those, and only while the key still holds them.
curl -X POST https://api.vezmo.com/api/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "vzm_live_ro_4Hq9ZbT1mK2xPv7d",
"client_secret": "'"$VEZMO_SECRET"'",
"scope": "accounts.read transactions.read"
}'{
"access_token": "eyJhbGciOiJFUzI1NiIs…",
"token_type": "Bearer",
"expires_in": 900,
"scope": "accounts.read transactions.read"
}- The token lasts 15 minutes (
expires_in: 900). There is no refresh token: ask again. The key's status, IP limits and your business's access are checked again on every call, so revoking a key stops it at once. - A secret found in public code (GitHub secret scanning): a live key is revoked at once and its tokens end; a test key can no longer run simulations (
403 key_leaked) and still reads test data until you revoke it. Every admin of your business is told. - 10 tokens a minute per key. Failed exchanges: 5 a minute per IP address (a correct secret always gets through).
- Answers are OAuth's own shape. Errors:
invalid_request,unsupported_grant_type,invalid_client(401, withWWW-Authenticate),invalid_scope, andunauthorized_clientwithcodeip_not_allowedorbusiness_api_paused. AlwaysCache-Control: no-store.
{
"error": "invalid_client",
"error_description": "The key ID or secret is wrong, or the key is switched off, revoked or expired."
}// Node 18+: one token, reused until a minute before it ends.
let cached = { token: null, until: 0 };
export async function accessToken() {
if (cached.token && Date.now() < cached.until) return cached.token;
const res = await fetch("https://api.vezmo.com/api/v1/oauth/token", {
method: "POST",
headers: {
Authorization: "Basic " + Buffer.from(`${process.env.VEZMO_KEY_ID}:${process.env.VEZMO_SECRET}`).toString("base64"),
"Content-Type": "application/x-www-form-urlencoded",
},
body: "grant_type=client_credentials",
});
if (!res.ok) throw new Error(`Token refused: ${res.status} ${await res.text()}`);
const body = await res.json();
cached = { token: body.access_token, until: Date.now() + (body.expires_in - 60) * 1000 };
return cached.token;
}Your first call
curl https://api.vezmo.com/api/v1/balances \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Vezmo-Version: 2026-11-14"Versions
Vezmo-Version: 2026-11-14 is the only version today. Your business is pinned to the newest version at its first call; calls without the header use the pin, and a header overrides it for that call only. Every answer echoes Vezmo-Version. An unknown version is 400 validation_failed with field: "Vezmo-Version".
Conventions
- Envelope:
{ success, data, meta, requestId, timestamp }; errors{ success: false, errors: [{ code, message, field?, help }], requestId }. - Money: integers in the currency's smallest unit with an ISO currency (
125000+USD= US$1,250.00). - Times: RFC 3339, UTC. Time filters must carry a zone, like
2026-10-01T00:00:00Z. - Ids:
acct_,txn_,stmt_,evt_,inc_,tr_. Another business's id answers404. - Masking: account numbers show the last 4 (
••••1234). Payer names are shown. - Filters: a parameter an endpoint doesn't take is
400 unsupported_filter, never ignored. - Caching: every answer is
Cache-Control: no-store.
Pagination
Lists are newest first. limit takes 1–100 (default 25). When meta.hasMore is true, pass meta.nextCursor as startingAfter. A cursor from another list or business is 400 validation_failed (field: "startingAfter").
curl "https://api.vezmo.com/api/v1/transactions?limit=50&startingAfter=txn_cm3k9q2xv0001" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# meta: { "hasMore": true, "nextCursor": "txn_cm3k9p7aa00ff" }Errors
{
"success": false,
"errors": [
{
"code": "insufficient_scope",
"message": "This API key doesn't have the statements.read permission.",
"scopes": ["statements.read"],
"help": "https://user.vezmo.com/docs/v1/errors#insufficient_scope"
}
],
"requestId": "1b1f55e8-b214-48a9-92f1-d6aad8f7a312"
}Every code is explained on Errors, and each error's help links straight to it.
Rate limits
- Every answer carries
RateLimit-Limit,RateLimit-Remaining,RateLimit-ResetandRequest-Id. A429addsRetry-AfterandVezmo-RateLimit-Reason. - Your key's own per-second limit applies, as on the rest of the API.
- Statements: 30 a minute per key, and 60 new statements a minute per business (each server enforcing its share; a month already made is free).