> ## Documentation Index
> Fetch the complete documentation index at: https://www.finta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Model

> How transactions, journal entries, and reports fit together

## Which endpoint should I use?

| I want to...                                | Use                                                                                             |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Drill into a report line item               | [GET /journal\_entries](/docs/api-reference/journal-entries/list-journal-entries) with `category_id` |
| Get categorized activity for a date range   | [GET /journal\_entries](/docs/api-reference/journal-entries/list-journal-entries)                    |
| Reconcile numbers with financial statements | [GET /journal\_entries](/docs/api-reference/journal-entries/list-journal-entries)                    |
| See the original bank/credit card feed      | [GET /transactions](/docs/api-reference/transactions/list-transactions)                              |
| Categorize one transaction                  | `PATCH /transactions/{id}` with a selectable `category_id`                                      |

**Journal entries** are the source of truth for all financial reports. Every number on the income statement, balance sheet, and cash flow is computed from journal entries. They are sourced from bank transactions, spreads (amortized expenses), capitalizations (depreciation schedules), CSV uploads, transfers, and other accounting operations.

**Transactions** are the raw bank and credit card feed: merchant names, approval status, account source. These are the original records before any accounting rules are applied, so they may not match report totals.

The `category_id` field links everything together. Every category entry on a report, every journal entry, and every transaction shares the same `category_id`.

## The drill-down pattern

To break down any line item on a report:

1. Pull a report (e.g. the [income statement](/docs/api-reference/reports/retrieve-income-statement)).
2. Find the category you want and grab its `category_id`.
3. Fetch the underlying journal entries:

```bash theme={null}
curl "https://app.finta.com/api/v1/journal_entries?category_id=cat_o5p6q7r8s9t0u1&start_date=2026-02-01&end_date=2026-02-28" \
  -H "Authorization: Bearer finta_your_key_here"
```

## Categorizing transactions

Transactions are the only writable resource in v1. To categorize one visible standard transaction, send a selectable category ID:

```bash theme={null}
curl -X PATCH "https://app.finta.com/api/v1/transactions/txn_a1b2c3d4e5f6g7" \
  -H "Authorization: Bearer finta_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"cat_v5e6f7g8h9i0j1"}'
```

The request body accepts only `category_id`. Success returns the full updated `Transaction`, including derived fields such as `categorized` and `category_name`, so update local caches from the response body instead of assuming only `category_id` changed.

Transfer transactions, split transactions, hidden transactions, and non-selectable categories cannot be categorized through this endpoint. These cases return `404 resource_missing`; bookkeeping validation failures return `422 category_update_failed`.

## Reading financial reports

The API returns three financial reports: [income statement](/docs/api-reference/reports/retrieve-income-statement), [balance sheet](/docs/api-reference/reports/retrieve-balance-sheet), and [cash flow](/docs/api-reference/reports/retrieve-cash-flow-statement).

<AccordionGroup>
  <Accordion title="Sign convention">
    Income and revenue are **positive**, expenses and taxes are **negative**. On the income statement, summing all section totals gives you `net_income_cents`. The same convention applies to cash flow: inflows are positive, outflows are negative.
  </Accordion>

  <Accordion title="Point-in-time vs. period activity">
    The balance sheet is a **point-in-time snapshot**, so its category entries use `balance_cents` (the balance as of a single date). The income statement and cash flow statement are **period reports**, so their category entries use `amount_cents` (activity over a date range).
  </Accordion>

  <Accordion title="Category hierarchy">
    Categories form a tree. Parent categories (e.g. "Cash", "Admin") appear in the array alongside their children, and each child references its parent via `parent_category_id`. Root-level categories have `parent_category_id: null`. To reconstruct the tree, group entries by `parent_category_id`. The `position` field gives you the sort order among siblings that share the same parent.

    The cash flow statement also includes **presentation groupings** ("Changes in Working Capital", "Non-Cash Expenses") as entries in `operating_activities.categories`. These use synthetic IDs prefixed with `grp_` (e.g. `grp_changes_in_working_capital`). Their children reference them via `parent_category_id`, following the same tree pattern.
  </Accordion>

  <Accordion title="Section totals">
    Each section (e.g. `revenue`, `expenses`) includes a `total_cents` that equals the sum of its **root-level** categories (those with `parent_category_id` null). Parent categories contain subtotals of their children, so summing all entries would double-count. You can use `total_cents` directly without summing categories yourself.
  </Accordion>

  <Accordion title="Drilling into line items">
    Each category entry includes a `category_id`. Pass it to `GET /journal_entries?category_id=cat_xxx` (with the same date range) to see every journal entry behind that line item. Synthetic grouping IDs (prefixed with `grp_`) are not real categories and cannot be used with the journal entries endpoint.
  </Accordion>
</AccordionGroup>