> ## Documentation Index > Fetch the complete documentation index at: https://help.agatabo.com/llms.txt > Use this file to discover all available pages before exploring further. # Viewing Journal Entries > Search, filter, and review transaction details and accounting records ## Overview **Journal entries** are the fundamental accounting records in Agatabo. Every financial transaction (member deposits, loan disbursements, expenses, dividends, reserve allocations) creates a journal entry showing exactly how accounts were debited and credited. **Automatic creation**: Most journal entries are created automatically when you perform business operations. You record transactions, and Agatabo handles the accounting. ## Accessing Journal Entries Click **General Ledger** in sidebar View searchable list of all journal entries Filter by date, kind, status, or search for specific entries See full transaction details, all debit/credit lines, and metadata *** ## Journal Entry Information Each entry displays: | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------- | | **ID** | Unique identifier for the journal entry | | **Transaction Date** | When the transaction occurred (not when entry was created) | | **Kind** | Type of transaction (SAVINGS\_DEPOSIT, LOAN\_DISBURSEMENT, DIVIDEND\_DISTRIBUTION, etc.) | | **Title** | Short label describing the transaction | | **Description** | Detailed explanation of what happened | | **Status** | POSTED (permanent, affects balances) or DRAFT (temporary, can be edited) | | **Lines** | Debit and credit details (must balance) | | **Created By** | User who recorded the transaction | | **Created At** | Timestamp when entry was created | | **Idempotency Key** | Unique key preventing duplicate entries | | **References** | Links to source entities (loan ID, member ID, reserve ID, dividend pool ID, etc.) | | **Parent Entry** | Parent journal entry (for multi-step transactions) | | **Reversed Entry** | Link to reversal entry (if reversed) | | **Documents** | Attached supporting documents | *** ## Journal Entry Kinds Agatabo uses these transaction types: ### Savings & Deposits * **SAVINGS\_DEPOSIT**: Member deposits funds to savings account * **ENTRY\_FEE**: Membership fee payment ### Loans * **LOAN\_DISBURSEMENT**: Loan principal disbursed to member * **LOAN\_PAYMENT**: Member makes loan payment (principal + interest) * **LOAN\_PENALTY**: Late payment penalty applied * **LOAN\_DEFAULT**: Loan written off as bad debt * **INTEREST\_PAID\_IN\_ADVANCE**: Upfront interest payment ### Expenses * **EXPENSE\_PAYMENT**: Operating expense payment * **BANK\_CHARGE**: Bank fees and charges ### Reserves * **RESERVE\_TOP\_UP**: Allocate funds from retained earnings to reserve * **RESERVE\_RELEASE**: Release funds from reserve back to retained earnings * **RESERVE\_EXPENSE**: Expense paid directly from reserve funds (creates parent RESERVE\_RELEASE + child RESERVE\_EXPENSE) ### Dividends * **DIVIDEND\_DISTRIBUTION**: Distribute retained earnings to member savings accounts ### Fixed Assets * **ASSET\_CASH\_PURCHASE**: Purchase asset with cash * **ASSET\_COLLATERAL**: Acquire asset as loan collateral * **ASSET\_GIFT**: Receive donated asset * **ASSET\_DISPOSAL**: Sell or dispose of asset * **CASH\_OPENING**: Record opening cash balance ### Administrative * **REVERSAL**: Reverse a previous journal entry * **PERIOD\_CLOSE**: Close accounting period and transfer net income to retained earnings [View complete ledger overview →](/tontines/general-ledger/overview) *** ## Understanding Journal Lines Each journal entry consists of 2 or more lines that must balance (total debits = total credits). ### Example 1: Member Deposit ``` Journal Entry ID: je-abc123 Transaction Date: June 10, 2026 Kind: SAVINGS_DEPOSIT Title: Savings Deposit Description: Alice monthly savings deposit Status: POSTED Created By: treasurer@org.com Lines: 1. DEBIT: Cash (organization:org123) 100,000 RWF 2. CREDIT: Savings (organizationUser:alice) 100,000 RWF Total Debits: 100,000 RWF Total Credits: 100,000 RWF ✓ Balanced ``` *** ### Example 2: Dividend Distribution ``` Journal Entry ID: je-def456 Transaction Date: June 12, 2026 Kind: DIVIDEND_DISTRIBUTION Title: Dividend Distribution Description: Q2 2026 Dividend Status: POSTED Created By: accountant@org.com Dividend Pool ID: pool-xyz789 Lines: 1. DEBIT: Retained Earnings (organization:org123) 5,000,000 RWF 2. CREDIT: Savings (organizationUser:alice) 100,000 RWF 3. CREDIT: Savings (organizationUser:bob) 100,000 RWF 4. CREDIT: Savings (organizationUser:carol) 100,000 RWF ... (50 members total) Total Debits: 5,000,000 RWF Total Credits: 5,000,000 RWF ✓ Balanced ``` *** ### Example 3: Reserve Allocation ``` Journal Entry ID: je-ghi789 Transaction Date: June 12, 2026 Kind: RESERVE_TOP_UP Title: Reserve Top Up Description: Emergency fund monthly allocation Status: POSTED Created By: treasurer@org.com Reserve ID: reserve-emergency-123 Lines: 1. DEBIT: Reserve Allocation (reserve:emergency) 1,000,000 RWF 2. CREDIT: Retained Earnings (organization:org123) 1,000,000 RWF Total Debits: 1,000,000 RWF Total Credits: 1,000,000 RWF ✓ Balanced ``` *** ## Filtering Journal Entries ### Filter by Date Range **Parameters:** * **from**: Start date (ISO format: YYYY-MM-DD) * **to**: End date (ISO format: YYYY-MM-DD) **Examples:** ``` This month: from=2026-06-01&to=2026-06-30 This quarter: from=2026-04-01&to=2026-06-30 This year: from=2026-01-01&to=2026-12-31 Last 30 days: from=2026-05-13&to=2026-06-12 ``` *** ### Filter by Kind **Parameter:** `kind` (journal\_entry\_kind enum) **Common filters:** ``` Show only deposits: kind=SAVINGS_DEPOSIT Show only loans: kind=LOAN_DISBURSEMENT Show only expenses: kind=EXPENSE_PAYMENT Show only dividends: kind=DIVIDEND_DISTRIBUTION Show only reserves: kind=RESERVE_TOP_UP ``` **Get all available kinds:** ``` GET /ledger-accounts/journal-entry-kinds ``` *** ### Filter by Status **Parameter:** `status` (DRAFT or POSTED) **DRAFT:** * Entry created but not yet finalized * Does not affect account balances * Can be edited or deleted * Not included in financial reports * Used for preparing entries before posting **POSTED:** * Entry finalized and locked * Affects account balances immediately * Cannot be edited or deleted (permanent) * Included in all financial reports * Creates audit trail **Examples:** ``` Show only posted: status=POSTED Show only drafts: status=DRAFT ``` *** ### Filter by Entity Reference **Member filter:** ``` organizationUserId=alice-123 ``` Shows all entries affecting this member (deposits, withdrawals, dividends, loans) **Loan filter:** ``` loanId=loan-456 ``` Shows all entries for this loan (disbursement, payments, penalties) **Reserve filter:** ``` reserveAllocationId=reserve-789 ``` Shows all entries for this reserve (top-ups, releases, expenses) **Dividend pool filter:** ``` dividendPoolId=pool-012 ``` Shows all entries for this dividend pool (distributions) **Bank account filter:** ``` bankAccountId=bank-345 ``` Shows all entries affecting this bank account *** ### Filter by Creator **Parameter:** `createdBy=organizationUserId` Shows all entries created by a specific user (useful for audit). **Example:** ``` createdBy=treasurer-user-123 ``` *** ### Filter by Parent/Reversal **Parent entry:** ``` parentJournalEntryId=je-parent-123 ``` Shows child entries of a specific parent (e.g., reserve-funded expenses) **Reversed entry:** ``` reversedEntryId=je-reversed-456 ``` Shows the reversal entry for a specific entry *** ### Search by Text **Parameter:** `searchTerm=text` Searches in: * Entry description * Entry title * Account names * Member names * Related entity details **Examples:** ``` searchTerm=alice (finds all entries mentioning Alice) searchTerm=emergency (finds emergency fund transactions) searchTerm=rent (finds rent expense entries) ``` *** ### Pagination **Parameters:** * **page**: Page number (default: 1) * **limit**: Items per page (default: 20, max varies by endpoint) **Example:** ``` page=1&limit=50 ``` **Response includes pagination metadata:** ```json theme={null} { "data": [...], "pagination": { "page": 1, "limit": 50, "totalCount": 532, "totalPages": 11, "hasNextPage": true, "hasPreviousPage": false } } ``` *** ## Viewing Entry Details Click on any journal entry to see: **Full transaction information:** * All debit and credit lines with account details * Scope keys showing which specific entity each line affects * Running balance (before/after) for each affected account * Transaction amount and balance verification **Metadata:** * Created by (user who created the entry) * Created at timestamp * Transaction date (when it occurred) * Idempotency key (prevents duplicates) **References:** * Source entity links (loan ID, member ID, reserve ID, dividend pool ID) * Parent journal entry (for multi-step transactions) * Reversed entry (if entry was reversed) **Supporting documents:** * Attached receipts, invoices, or documentation * Document type and description **Audit trail:** * Who created the entry * When it was created * What triggered its creation * Related transactions *** ## Common Use Cases ### Finding a Specific Transaction **By transaction date and amount:** Set from/to dates around transaction date Most recent first Look for matching transaction amount Verify it's the correct transaction *** ### Reviewing All Transactions for a Member **View member's financial history:** Set organizationUserId parameter Chronological order See deposits, withdrawals, loans, dividends Check that savings balance matches entries *** ### Investigating an Accounting Error **Find and diagnose discrepancies:** Identify which account is unbalanced View account's current balance List all entries affecting the account Look for unbalanced or incorrect entries Report issue for correction (may require reversal) *** ### Auditing Dividend Distributions **Verify dividend distribution accuracy:** Set dividendPoolId parameter See DIVIDEND\_DISTRIBUTION journal entry Verify each member received correct amount Confirm total credits equal total debit to retained earnings *** ### Tracking Reserve Activity **Monitor reserve allocations and releases:** Set reserveAllocationId parameter Show RESERVE\_TOP\_UP, RESERVE\_RELEASE, and RESERVE\_EXPENSE See all top-ups and releases over time Ensure balance matches expected based on entries *** ## Reversing Journal Entries **Reversals are permanent**: Reversing a journal entry creates a new REVERSAL entry that exactly offsets the original. Both entries remain in the ledger permanently for audit trail. Most transactions should not be reversed manually - use proper business operations to correct errors. ### When to Reverse **Appropriate uses:** * Correcting accounting errors (wrong account, wrong amount) * Voiding duplicate entries * Correcting period mismatches (transaction in wrong accounting period) **Inappropriate uses:** * Normal business corrections (use proper operations instead) * Member requested refunds (use withdrawal transaction) * Loan payment errors (use loan adjustment features) ### How Reversals Work **Original entry:** ``` DEBIT: Cash +100,000 CREDIT: Savings (Alice) +100,000 ``` **Reversal entry (automatically created):** ``` Kind: REVERSAL Description: Reversal of je-abc123: [reason] DEBIT: Savings (Alice) -100,000 CREDIT: Cash -100,000 ``` **Net effect:** * Original entry remains in ledger (for audit) * Reversal entry offsets it (nullifies impact) * Both entries permanently recorded * Account balances return to pre-transaction state ### API Endpoint ``` POST /ledger-accounts/journal/:journalEntryId/reverse Headers: x-organization-id: x-idempotency-key: Body: { "reversalDate": "2026-06-15", "description": "Reason for reversal", "skipNegativeBalanceCheck": false } ``` **Permission required**: `ledger:write` - Only accountants and administrators can reverse entries. *** ## Reconciliation Journal entries should match external records: **Cash reconciliation:** * Compare journal entries (kind=CASH\_\*) with bank statements * Ensure all deposits, withdrawals, and fees are recorded * Investigate discrepancies immediately **Member savings reconciliation:** * Compare entries affecting SAVINGS accounts with member expectations * Verify deposits and withdrawals match member records * Check dividend distributions are correct **Loan reconciliation:** * Ensure loan disbursements match loan schedules * Verify payments applied correctly (principal vs. interest) * Check penalties and fees are accurate *** ## Exporting Journal Entries **Use cases:** * External audit (provide transaction log to auditors) * Analysis (download to Excel for pivot tables) * Compliance (transaction log for regulators) * Backup (archive accounting records) **How to export:** Date range, kind, status, etc. Choose export format Excel (.xlsx), CSV (.csv), or PDF Save exported journal entries **Export includes:** * All visible journal entries matching filters * All debit and credit lines for each entry * Account details, amounts, dates, descriptions * Formatted for readability in chosen format *** ## Best Practices **Working with journal entries:** **Regular Review:** * Review journal entries monthly for accuracy * Spot-check automatic entries to verify correctness * Monitor for unusual or unexpected entries * Report suspicious entries to management immediately **Filtering:** * Use specific filters to narrow results (date + kind + entity) * Start broad, then narrow down when searching * Save common filter combinations for frequent use **Manual Entries:** * NEVER create manual journal entries without accountant approval * Understand double-entry basics before attempting manual entries * Always document reason for manual entries clearly * Verify entry balances before posting **Audit Trail:** * Keep exported journal entry reports for 7+ years * Cross-reference with source documents during audits * Maintain documentation for all manual entries * Track all reversals with clear explanations **Error Prevention:** * Trust automatic entries (they're tested and correct) * Don't reverse entries unless absolutely necessary * Use proper business operations to correct most errors * Consult accountant before manual interventions *** ## Technical Details ### API Endpoints **Search journal entries:** ``` GET /ledger-accounts/journal-search Query parameters: searchTerm?: string from?: YYYY-MM-DD to?: YYYY-MM-DD kind?: journal_entry_kind status?: DRAFT | POSTED page?: number (default 1) limit?: number (default 20) organizationUserId?: string loanId?: string bankAccountId?: string dividendPoolId?: string reserveAllocationId?: string createdBy?: string parentJournalEntryId?: string reversedEntryId?: string roleDefinitionId?: string installmentId?: string Response: { "message": "Journal entries retrieved successfully", "data": [ { "id": "je-123", "kind": "SAVINGS_DEPOSIT", "transactionDate": "2026-06-10", "status": "POSTED", "title": "Savings Deposit", "description": "Alice monthly deposit", "lines": [ { "id": "line-1", "side": "DEBIT", "amount": "100000", "ledgerAccount": { "id": "acc-cash", "role": "CASH", "type": "ASSET", "name": "Cash" } }, { "id": "line-2", "side": "CREDIT", "amount": "100000", "ledgerAccount": { "id": "acc-alice-savings", "role": "SAVINGS", "type": "LIABILITY", "name": "Alice Savings", "refId": "alice-123" } } ] } ], "pagination": { "page": 1, "limit": 20, "totalCount": 532, "totalPages": 27, "hasNextPage": true, "hasPreviousPage": false } } ``` **Get specific journal entry:** ``` GET /ledger-accounts/journal/:journalEntryId Response: { "message": "Journal entry retrieved successfully", "data": { "id": "je-123", "kind": "SAVINGS_DEPOSIT", "transactionDate": "2026-06-10", "status": "POSTED", "title": "Savings Deposit", "description": "Alice monthly deposit", "idempotencyKey": "unique-key-123", "createdBy": "treasurer-123", "createdAt": "2026-06-10T14:30:00Z", "documents": [], "lines": [...] } } ``` **Get journal entry kinds:** ``` GET /ledger-accounts/journal-entry-kinds Response: { "message": "Journal entry kinds retrieved successfully", "data": [ { "value": "SAVINGS_DEPOSIT", "label": "Savings Deposit", "isFilterable": true }, { "value": "LOAN_DISBURSEMENT", "label": "Loan Disbursement", "isFilterable": true }, ... ] } ``` **Get account activity:** ``` GET /ledger-accounts/:ledgerAccountId/activity (Same query parameters and response structure as journal-search) ``` **Get role transactions:** ``` GET /ledger-accounts/role-transactions/:roleDefinitionId (Same query parameters and response structure as journal-search) ``` *** ## Permissions Required | Action | Permission | Scope | | --------------------- | -------------- | ---------------------- | | View journal entries | `ledger:read` | ANY or specific entity | | Search all entries | `ledger:read` | ANY | | View specific entry | `ledger:read` | Entry's organization | | View account activity | `ledger:read` | Account's organization | | Reverse entry | `ledger:write` | ANY | **Typical roles**: * Administrators and Accountants: `ledger:read` and `ledger:write` (ANY scope) - can view and modify all entries * Treasurers: `ledger:read` (ANY scope) - can view all entries but not modify * Regular members: `ledger:read` (own organizationUserId scope) - can only view their own transactions *** ## Need Help? Learn accounting basics Understand account roles Complete accounting system overview Create manual accounting entries Reconcile accounts and detect errors