Skip to main content

​
Which endpoint should I use?

I want to…Use
Drill into a report line itemGET /journal_entries with category_id
Get categorized activity for a date rangeGET /journal_entries
Reconcile numbers with financial statementsGET /journal_entries
See the original bank/credit card feedGET /transactions
Categorize one transactionPATCH /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).
  2. Find the category you want and grab its category_id.
  3. Fetch the underlying journal entries:
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: 
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, balance sheet, and cash flow.
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.
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).
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.
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.
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.