# Accounts API

Read your Vezmo accounts from your own systems, covering what the Accounts API reads (accounts, balances, transactions, statements and events), how a call is made, versions, amounts, paging, errors and limits, and what no key can ever do.

Source: https://vezmo.com/docs/developers/accounts-api


## Overview

The Accounts API lets your own systems read your Vezmo accounts: your ERP, your accounting software, a treasury
dashboard or a script your finance team runs. It reads the same accounts, balances, transactions and statements you
see in the dashboard, and it can tell your server when money arrives.

In this first phase it only reads. No key can send money, add a recipient, approve anything or change your team.

We switch the Accounts API on business by business. To ask for it, see
[Get access to the Accounts API](/docs/developers/accounts-api-access).

## What it reads

| What | Permission | What you get |
| --- | --- | --- |
| Accounts and balances | `accounts.read` | Each of your accounts with its currency, status, bank name and rails, the account number masked to its last 4 digits, and each currency's balance: available, pending (arrived, not yet credited), on its way out, and the total. |
| Transactions | `transactions.read` | Every line booked on your balances, newest first: money in, transfers, fees, returns and corrections. You can filter by account, currency, direction, type, status, dates, amount or transfer. |
| Statements | `statements.read` | One statement per account per month, as JSON, CSV or PDF. See [Statements by API](/docs/developers/accounts-api-statements). |
| Events | `events.read` | What happened on your accounts in the last 30 days, such as money arriving or a statement being ready. The same events can reach your server as webhooks: see [Webhooks for Accounts](/docs/developers/accounts-api-webhooks). |

A key gets only the permissions you choose when you make it. See
[Keys and permissions for the Accounts API](/docs/developers/accounts-api-keys).

## How a call works

(Diagram: Your server sends the key ID and secret to POST /oauth/token and gets an access token that lasts 15 minutes. It sends that token with each read: accounts, balances, transactions, statements and events.)

1. Your server sends the key ID and the secret to `POST /oauth/token`, the standard OAuth 2.0 client-credentials
   request. The answer holds an access token that lasts 15 minutes. There is no refresh token: ask for a new one when
   it runs out.
2. It sends that token as `Authorization: Bearer <token>` on every read, to the base URL
   `https://api.vezmo.com/api/v1`.

Every request and answer, with examples in several languages, is in the
[Accounts API reference](https://user.vezmo.com/docs/v1/accounts-api).

## Versions

Send the `Vezmo-Version` header to say which version of the API you built against. Today there is one:
`2026-11-14`.

- Your business is pinned to the newest version at its first call. Calls without the header use that version.
- A header with another version applies to that one call only, so you can try a new version before you move to it.
- Every answer says which version it used. An unknown version is refused with `400`.

## Amounts, times, ids and lists

- **Amounts** are whole numbers in the currency's smallest unit, with the currency beside them: US$1,250.00 is
  `125000` with `USD`.
- **Times** are UTC, written like `2026-10-01T00:00:00Z`. A time you send in a filter must carry its zone.
- **Ids** start with what they are: `acct_` an account, `txn_` a transaction, `stmt_` a statement, `evt_` an event.
  An id of another business answers `404`, as if it didn't exist.
- **Lists** come newest first, 25 at a time (`limit` takes 1 to 100). When `meta.hasMore` is true, send
  `meta.nextCursor` as `startingAfter` for the next page.
- **Filters** the endpoint doesn't take are refused with `400` and the code `unsupported_filter`, never ignored.

## Errors

Every error has the same shape: `success` is false, and `errors` lists each problem with a `code`, a `message`, the
`field` it is about when there is one, and a `help` link to its explanation in the API reference.

| Code | What it means |
| --- | --- |
| `authentication_failed` | The access token is missing or not one of ours. |
| `token_expired` | The access token ran out. Get a new one from `POST /oauth/token`. |
| `key_revoked` · `key_expired` | The key was switched off, revoked or passed its expiry date. |
| `insufficient_scope` | The key doesn't have the permission this endpoint needs. |
| `api_access_not_enabled` | The Accounts API isn't switched on for your business. |
| `ip_not_allowed` | The key has IP limits and the call came from another address. |
| `validation_failed` · `unsupported_filter` | A value or a parameter isn't right. `field` names it. |
| `not_found` | No such object for your business. |
| `rate_limited` | Too many requests. Wait for the time in `Retry-After`. |
| `service_unavailable` | Busy on our side. Try again after the time in `Retry-After`. |

The full list is on [Errors in the API reference](https://user.vezmo.com/docs/v1/errors).

## Limits

- Each answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, and a `Request-Id` to quote if
  you contact us.
- Access tokens: 10 a minute per key. Failed token requests: 5 a minute from one IP address.
- Statements: 30 a minute per key, and 60 new statements a minute per business. A month already made doesn't count.
- Your key's own limit applies to every call, as for the rest of the API. See
  [Rate limits](/docs/developers/rate-limits).

## What no key can ever do

- Approve anything, its own requests included.
- Make, see, roll or change API keys.
- Change your team, roles, limits, IP limits or security settings.
- Add or change webhook endpoints.
- Switch the Accounts API on or off for your business.

## Questions

### Can I send money with the API?

Not yet. This phase only reads. Sending, with a person in your business approving each payment, comes in a later phase.

### Can I see full account numbers?

Not by API in this phase. Account numbers are masked to their last 4 digits. The full details are in the dashboard.

### Do test keys work?

Yes. A test key reads the sandbox, with simulated accounts and no real money. See
[Sandbox for the Accounts API](/docs/developers/accounts-api-sandbox).

## Related

- [Get access to the Accounts API](/docs/developers/accounts-api-access)
- [Keys and permissions for the Accounts API](/docs/developers/accounts-api-keys)
- [Statements by API](/docs/developers/accounts-api-statements)
- [Webhooks for Accounts](/docs/developers/accounts-api-webhooks)
- [Sandbox for the Accounts API](/docs/developers/accounts-api-sandbox)
- [Accounts API reference](https://user.vezmo.com/docs/v1/accounts-api)

Vezmo is a financial technology company, not a bank. Banking, stablecoin and card services are provided by regulated
partners.
