Account Object

An Account represents a bank account or credit card that holds transactions.

Object Structure

{
  "id": "acc123xyz",
  "name": "Main Business Account",
  "category": "bank",
  "description": "Primary operating account for business expenses",
  "acc_no": "1234567890",
  "currency": "INR",
  "color": "#3B82F6",
  "opening_balance": 50000.00,
  "opening_balance_date": "2025-01-01",
  "status": "active",
  "upload_frequency": "weekly",
  "created_at": "2025-01-01T00:00:00.000Z",
  "review": {
    "is_done": true,
    "at": "2025-01-06T14:30:00.000Z",
    "type": "human",
    "by": "user123",
    "work_record_id": "wr456"
  }
}

Fields

Core Fields

Field	Type	Required	Description
id	string	Auto	12-character unique identifier
name	string	Yes	Display name for the account
category	string	No	Account type (see categories below)
description	string	No	Additional notes about the account
acc_no	string	No	Bank account number (partial or full)

Financial Fields

Field	Type	Description
currency	string	3-letter currency code (e.g., INR, USD, EUR)
opening_balance	number	Starting balance when account was added
opening_balance_date	string	Date when opening_balance was valid (YYYY-MM-DD). Auto-set to today if not provided when opening_balance is set.

Display Fields

Field	Type	Description
color	string	Hex color code for UI display (e.g., #3B82F6)

Status Fields

Field	Type	Description
status	string	Lifecycle state: `active`, `retired`, or `quarantined`
upload_frequency	string	Expected statement upload frequency
created_at	string	ISO 8601 timestamp of creation

Review Fields

Field	Type	Description
review	object	Review status (null if never reviewed)
review.is_done	boolean	Whether review is complete
review.at	string	ISO 8601 timestamp of review
review.type	string	Reviewer type: `ai` or `human`
review.by	string	User ID if human reviewer, null if AI
review.work_record_id	string	WorkRecord documenting the review

Account Categories

Category	Description
`bank`	Savings or current bank account
`credit_card`	Credit card account

Upload Frequencies

The upload_frequency field indicates how often statements should be uploaded:

Frequency	Description
`daily`	Daily uploads expected
`weekly`	Weekly uploads expected
`monthly`	Monthly uploads expected
`quarterly`	Quarterly uploads expected
`manual`	Uploaded on demand

This is used for tracking and reminders, not enforced programmatically.

Account Identifiers

When statements are uploaded, the system matches them to accounts using the identifier field. This is an array of strings that can include:

Full account numbers
Partial account numbers (last 4 digits)
Custom identifiers

The API does not expose the identifier field for security. Account matching happens automatically during statement processing.

Lifecycle

Every account has a status:

active — in use; shown everywhere and counted in reports.
retired — closed but real; hidden from day-to-day UI, still counted in reports and history.
quarantined — suspect or in-progress data; hidden from the UI and excluded from reports.

Change it with Update Account (PUT with { "status": "retired" }), and filter a list by it with ?status=active. These states hide an account without losing its data; to remove one entirely use Delete Account (a guarded hard delete).

Field Selection

When retrieving accounts, use the fields parameter to request only specific fields:

GET /api/v1/accounts?fields=id,name,category,currency

Available fields: id, name, category, description, acc_no, currency, color, opening_balance, opening_balance_date, status, upload_frequency, review, created_at

Example: Bank Account

{
  "id": "acc001bank",
  "name": "HDFC Savings",
  "category": "bank",
  "description": "Personal savings account",
  "acc_no": "XXXX7890",
  "currency": "INR",
  "color": "#10B981",
  "opening_balance": 100000.00,
  "opening_balance_date": "2024-06-15",
  "status": "active",
  "upload_frequency": "monthly",
  "created_at": "2024-06-15T00:00:00.000Z",
  "review": {
    "is_done": true,
    "at": "2024-07-01T10:00:00.000Z",
    "type": "human",
    "by": "user123",
    "work_record_id": "wr789"
  }
}

Example: Credit Card

{
  "id": "acc002card",
  "name": "ICICI Amazon Pay",
  "category": "credit_card",
  "description": "Rewards credit card",
  "acc_no": "XXXX4567",
  "currency": "INR",
  "color": "#EF4444",
  "opening_balance": 0,
  "opening_balance_date": null,
  "status": "active",
  "upload_frequency": "monthly",
  "created_at": "2024-08-01T00:00:00.000Z",
  "review": null
}

Accounts API - Overview and all endpoints
Create Account - Create endpoint
Transaction Object - Transaction reference
Statement Object - Statement reference