Skip to content

Ledger API

Double-entry general ledger: accounts, journal entries, sub-ledger views, and financial reports.

Base permission: IsViewerOrAbove (read), IsAdminOrAbove (write)

Accounts

Method Path Description Permission
GET /ledger/accounts List GL accounts IsViewerOrAbove
GET /ledger/accounts/{id} Get account IsViewerOrAbove
POST /ledger/accounts Create account IsAdminOrAbove
GET /ledger/accounts/{id}/balance Get account balance IsViewerOrAbove

Create Account

POST /api/v1/ledger/accounts

{
  "code": "1200",
  "name": "Loans Receivable - Consumer",
  "account_type": "asset",
  "parent_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Outstanding consumer loan principal"
}

Account Types

Type Normal Balance Description
asset Debit Resources owned (cash, receivables)
liability Credit Obligations owed
equity Credit Owner's equity
revenue Credit Income earned
expense Debit Costs incurred

Get Account Balance

Returns the derived balance computed from all journal entry lines.

GET /api/v1/ledger/accounts/{id}/balance

Response:

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "1100",
  "name": "Cash",
  "balance": "125000.00",
  "as_of": "2026-01-15T23:59:59Z"
}

Note

Account balances are always derived from journal entry lines, never stored directly. This is a core ledger invariant.

Journal Entries

Method Path Description Permission
GET /ledger/entries List journal entries IsViewerOrAbove
GET /ledger/entries/{id} Get journal entry IsViewerOrAbove
POST /ledger/entries Create journal entry IsAdminOrAbove
POST /ledger/entries/{id}/post Post journal entry IsAdminOrAbove
POST /ledger/entries/{id}/reverse Reverse journal entry IsAdminOrAbove

Create Journal Entry

POST /api/v1/ledger/entries

{
  "entry_date": "2026-01-15",
  "description": "Manual adjustment",
  "reference_type": "manual",
  "lines": [
    {
      "account_id": "...",
      "debit": "100.00",
      "credit": "0.00",
      "description": "Debit adjustment"
    },
    {
      "account_id": "...",
      "debit": "0.00",
      "credit": "100.00",
      "description": "Credit adjustment"
    }
  ]
}

Ledger Invariants

  • Every journal entry must balance: SUM(debits) = SUM(credits)
  • Posted entries are immutable --- corrections must use reversing entries
  • The API validates balance before accepting the entry

Post Journal Entry

Changes entry status from draft to posted. Posted entries cannot be modified.

POST /api/v1/ledger/entries/{id}/post

Reverse Journal Entry

Creates a new entry with mirror debits/credits, linked to the original.

POST /api/v1/ledger/entries/{id}/reverse

{
  "reason": "Incorrect account assignment"
}

Preconditions: Entry must be in posted status.

Ledger Reports

Sub-Ledger

View all GL entries for a specific loan.

GET /api/v1/ledger/loans/{loan_id}/sub-ledger

Response:

[
  {
    "id": "...",
    "entry_date": "2026-01-15",
    "description": "Loan disbursement",
    "reference_type": "disbursement",
    "lines": [
      {"account": "Loans Receivable", "debit": "10000.00", "credit": "0.00"},
      {"account": "Cash", "debit": "0.00", "credit": "10000.00"}
    ]
  }
]

Trial Balance

GET /api/v1/ledger/trial-balance?as_of_date=2026-01-31

Response:

{
  "as_of_date": "2026-01-31",
  "accounts": [
    {"code": "1100", "name": "Cash", "debit": "125000.00", "credit": "0.00"},
    {"code": "1200", "name": "Loans Receivable", "debit": "850000.00", "credit": "0.00"},
    {"code": "4100", "name": "Interest Income", "debit": "0.00", "credit": "12500.00"}
  ],
  "total_debits": "975000.00",
  "total_credits": "975000.00"
}

GL Detail

GET /api/v1/ledger/gl-detail?start_date=2026-01-01&end_date=2026-01-31&account_id={id}

Returns all journal entry lines for a specific account within a date range.

System-Generated Entries

Most GL entries are created automatically by business operations:

Event Debit Credit
Loan disbursement Loans Receivable Cash
Payment (principal) Cash Loans Receivable
Payment (interest) Cash Interest Income
Payment (fees) Cash Fee Income
Interest accrual Interest Receivable Interest Income
Fee assessment Fees Receivable Fee Income
Fee waiver Fee Income Fees Receivable
Payment reversal Reverse of original Reverse of original
Charge-off Charge-Off Expense Loans Receivable
Collateral liquidation Cash Loans Receivable

See Also