API: Accounts

The accounts resource lets you manage project accounts via the External API: list accounts, get one by id, create, update, and delete.

Scopes

• accounts:read — list accounts and get a single account
• accounts:write — create, update, delete

Base path and headers

All methods: POST {{base_url}}/v1/accounts/<action>.

Required headers:

• Content-Type: application/json
• X-Api-Key: <your_api_key>

For create/update/delete you can send Idempotency-Key: <uuid> — repeated requests with the same key within 24h return the cached response.

1. List accounts

POST /v1/accounts/list. Requires accounts:read. projectId is derived from the API key; request body can include only includeArchived.

Request

{
  "meta": { "requestId": "optional" },
  "data": {
    "includeArchived": false
  }
}

Response (success, 200)

{
  "success": true,
  "data": {
    "projectId": "project-uuid",
    "accounts": [
      {
        "id": "account-uuid",
        "projectId": "project-uuid",
        "ownerId": "owner-uuid",
        "accountKind": "cash",
        "financialRole": "asset",
        "displayName": "Cash",
        "status": "active",
        "createdAt": "2026-03-07T12:00:00.000Z",
        "updatedAt": "2026-03-07T12:00:00.000Z",
        "currency": {
          "id": "currency-uuid",
          "code": "RUB",
          "symbol": "₽",
          "decimalPlaces": 2
        }
      }
    ],
    "totalCount": 1
  },
  "meta": {
    "requestId": "...",
    "serverTime": "2026-03-07T12:00:00.000Z",
    "executionTimeMs": 15,
    "project": { "id": "...", "timezone": "Europe/Moscow", "locale": "ru-RU", "currency": "RUB" },
    "rateLimit": { "minute": { "limit": 120, "remaining": 119, "resetAt": "..." }, "hour": { ... }, "day": { ... }, "month": { ... } }
  }
}

Example (cURL)

curl -X POST "https://api-external.budgeter.online/v1/accounts/list" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"data":{"includeArchived":false}}'

Errors: 401 (invalid/revoked key), 403 (insufficient scope or temporary ban), 429 (rate limit).

2. Get account

POST /v1/accounts/get. Requires accounts:read. Returns a single account by accountId.

Request

{
  "data": {
    "accountId": "account-uuid"
  }
}

Response (success, 200)

{
  "success": true,
  "data": {
    "id": "account-uuid",
    "projectId": "project-uuid",
    "ownerId": "owner-uuid",
    "accountKind": "bank_account",
    "financialRole": "asset",
    "assetClass": "fiat",
    "displayName": "Main account",
    "defaultCurrencyId": "currency-uuid",
    "status": "active",
    "createdAt": "2026-03-07T12:00:00.000Z",
    "updatedAt": "2026-03-07T12:00:00.000Z",
    "currency": { "id": "...", "code": "RUB", "symbol": "₽", "decimalPlaces": 2 },
    "settings": {},
    "visibility": {},
    "uiPrefs": {}
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 8, "project": { ... }, "rateLimit": { ... } }
}

Errors: 400 (missing accountId), 404 (account not found or no access), 401/403/429.

3. Create account

POST /v1/accounts/create. Requires accounts:write. Required fields: accountKind, displayName, defaultCurrencyId.

Request

{
  "data": {
    "accountKind": "cash",
    "displayName": "Cash",
    "defaultCurrencyId": "currency-uuid"
  }
}

Optional: financialRole, assetClass, currencyMode, ownershipScope, color, icon, emoji, status, settings, visibility, uiPrefs.

Response (success, 200)

{
  "success": true,
  "data": {
    "id": "new-account-uuid",
    "projectId": "project-uuid",
    "ownerId": "owner-uuid",
    "accountKind": "cash",
    "financialRole": "asset",
    "displayName": "Cash",
    "defaultCurrencyId": "currency-uuid",
    "status": "active",
    "createdAt": "2026-03-07T12:00:00.000Z",
    "updatedAt": "2026-03-07T12:00:00.000Z",
    "currency": { "id": "...", "code": "RUB", "symbol": "₽", "decimalPlaces": 2 },
    "settings": {},
    "visibility": {},
    "uiPrefs": {}
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 45, "project": { ... }, "rateLimit": { ... } }
}

Example (cURL)

curl -X POST "https://api-external.budgeter.online/v1/accounts/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"data":{"accountKind":"cash","displayName":"Cash","defaultCurrencyId":"CURRENCY_UUID"}}'

Errors: 400 (validation), 403 (scope), 401/429.

4. Update account

POST /v1/accounts/update. Requires accounts:write. Only accountId is required; other fields are optional.

Request

{
  "data": {
    "accountId": "account-uuid",
    "displayName": "New name",
    "status": "archived"
  }
}

Response (success, 200)

{
  "success": true,
  "data": {
    "id": "account-uuid",
    "projectId": "project-uuid",
    "ownerId": "owner-uuid",
    "accountKind": "cash",
    "displayName": "New name",
    "status": "archived",
    "updatedAt": "2026-03-07T12:05:00.000Z",
    "currency": { ... },
    "settings": {},
    "visibility": {},
    "uiPrefs": {}
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 22, "project": { ... }, "rateLimit": { ... } }
}

Errors: 400 (missing accountId), 404 (account not found), 403/401/429.

5. Delete account

POST /v1/accounts/delete. Requires accounts:write. Default is soft delete (hardDelete: false). hardDelete: true only for project owner.

Request

{
  "data": {
    "accountId": "account-uuid",
    "hardDelete": false
  }
}

Response (success, 200)

{
  "success": true,
  "data": {
    "accountId": "account-uuid",
    "deleted": true,
    "deletionType": "soft"
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 18, "project": { ... }, "rateLimit": { ... } }
}

Errors: 400, 404, 403, 401/429.

Limits

General API limits apply (120/min, 3000/hour, etc.). Additionally: at most 60 mutating requests per minute (create, update, delete) per API key.

See also

External API: basics — base URL, getting an API key, error codes, limits.