Skip to main content
Accounts hold balances for an entity. Each account is denominated in a single currency. An entity must have approved status before accounts can be created for them.

​
The Account object

​
id
string
Unique account identifier. Prefix: acc_.
​
entity_id
string
The ID of the entity this account belongs to.
​
type
string
Account type. One of checking, debit, operational, or safeguard.
​
currency
string
ISO 4217 currency code (e.g. USD, GBP, EUR).
​
display_name
string
Human-readable label for the account.
​
nuvion_ban
string
Nuvion internal bank account number used for routing. Treat this as read-only.
​
balance
object
Current balance state of the account. All amounts are in the smallest currency unit (e.g. cents for USD).
​
meta
object
Set of key-value pairs for storing additional platform-defined data.
​
created
number
Unix timestamp in milliseconds when the account was created.
​
updated
number
Unix timestamp in milliseconds when the account was last updated.
Example
{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 150000,
    "current": 150000
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
Always use balance.available when checking if an entity has sufficient funds. balance.current includes amounts pending settlement that are not yet spendable.

​
Create an account

Creates a new account for an approved entity. The entity must have status: "approved" before accounts can be opened. 
curl -X POST https://api.nuvion.dev/accounts \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "ent_01HXYZ1234ABCD",
    "type": "checking",
    "currency": "USD",
    "display_name": "Main USD Account"
  }'

​
Request parameters

​
entity_id
string
required
The ID of the entity to open this account for. The entity must have status: "approved".
​
type
string
required
Account type. One of checking, debit, operational, or safeguard.
​
currency
string
required
ISO 4217 currency code. Supported values: USD, GBP, EUR.
​
display_name
string
required
Human-readable label for the account. Maximum 100 characters.
​
meta
object
Key-value metadata to attach to the account. Values must be strings.

​
Response

Returns the created account object. The balance is 0 for both available and current at creation.
Response
{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 0,
    "current": 0
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
The first account created for an entity automatically becomes their default account.

​
List accounts

Returns a paginated list of accounts. Filter by entity, currency, or account type. 
curl "https://api.nuvion.dev/accounts?entity_id=ent_01HXYZ1234ABCD&limit=20" \
  -H "Authorization: Bearer $NUVION_API_KEY"

​
Request parameters

​
entity_id
string
Filter accounts by entity ID. Required when authenticating with an API key.
​
currency
string
Filter by ISO 4217 currency code (e.g. USD).
​
type
string
Filter by account type. One of checking, debit, operational, or safeguard.
​
limit
integer
Number of results to return. Between 1 and 100. Defaults to 20.
​
cursor
string
Pagination cursor from a previous response. Omit for the first page.

​
Response

Returns a paginated list of account objects.
Response
{
  "data": [
    {
      "id": "acc_01HXYZ5678EFGH",
      "entity_id": "ent_01HXYZ1234ABCD",
      "type": "checking",
      "currency": "USD",
      "display_name": "Main USD Account",
      "nuvion_ban": "NVN0000012345",
      "balance": {
        "available": 150000,
        "current": 150000
      },
      "meta": {},
      "created": 1735725600000,
      "updated": 1735725600000
    }
  ],
  "meta": {
    "pagination": {
      "has_next": true,
      "has_previous": false,
      "next_cursor": "cursor_abc123",
      "previous_cursor": null,
      "total_count": 42
    }
  }
}

​
Get an account

Retrieves an existing account by ID. 
curl "https://api.nuvion.dev/accounts/acc_01HXYZ5678EFGH" \
  -H "Authorization: Bearer $NUVION_API_KEY"

​
Request parameters

​
account_id
string
required
The ID of the account to retrieve.
​
entity_id
string
The ID of the entity that owns the account. Required when authenticating with an API key.

​
Response

Returns the account object.
Response
{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 150000,
    "current": 162500
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735812000000
}