# Finance API Reference
AskRobots includes a full double-entry accounting system with a REST API. Track income, expenses, assets, liabilities, and equity across multiple entities — then pull reports as JSON for dashboards, mobile apps, or integrations.
## Authentication
All endpoints require token authentication:
```
Authorization: Token YOUR_API_TOKEN
```
Get your token at [askrobots.com/userauth/apikeys/](https://askrobots.com/userauth/apikeys/).
---
## Entities
An entity is a business, project, or person whose books you're tracking. Each entity has its own chart of accounts and journal entries.
### List entities
```
GET /finance/api/entities/
```
Query params: `?search=`, `?mode=simple|standard|double_entry`, `?status=active|archived`
### Create entity
```
POST /finance/api/entities/
{
"name": "My Company",
"mode": "double_entry",
"description": "Main business entity"
}
```
Modes:
- **simple** — Income and Expenses only (2 accounts)
- **standard** — Common accounts for small businesses
- **double_entry** — Full chart of accounts (30 accounts)
### Setup default accounts
```
POST /finance/api/entities/{id}/setup_accounts/
```
Auto-creates the default chart of accounts for the entity's mode. Returns the list of created accounts.
### Get / Update / Delete
```
GET /finance/api/entities/{id}/
PUT /finance/api/entities/{id}/
DELETE /finance/api/entities/{id}/
```
---
## Accounts
Accounts belong to an entity and are categorized by type: asset, liability, equity, income, or expense.
### List accounts
```
GET /finance/api/accounts/
```
Query params: `?entity={uuid}`, `?account_type=asset|liability|equity|income|expense`, `?search=`
### Create account
```
POST /finance/api/accounts/
{
"entity": "uuid",
"name": "Advertising",
"account_type": "expense",
"code": "5410",
"description": "Ad spend across all channels"
}
```
### Get / Update / Delete
```
GET /finance/api/accounts/{id}/
PUT /finance/api/accounts/{id}/
DELETE /finance/api/accounts/{id}/
```
---
## Journals
A journal entry records a financial transaction. In double-entry mode, each journal has lines that must balance (total debits = total credits).
### List journals
```
GET /finance/api/journals/
```
Query params: `?entity={uuid}`, `?status=draft|posted`, `?date_from=2026-01-01`, `?date_to=2026-12-31`, `?search=`, `?contact={uuid}`, `?project={uuid}`
### Create journal with lines
Create a journal and its lines in a single request using `lines_data`:
```
POST /finance/api/journals/
{
"entity": "uuid",
"date": "2026-03-10",
"description": "Office supplies from Amazon",
"lines_data": [
{
"account": "expense-account-uuid",
"direction": "debit",
"amount": "49.99",
"currency": "usd-currency-uuid",
"exchange_rate": "1"
},
{
"account": "credit-card-account-uuid",
"direction": "credit",
"amount": "49.99",
"currency": "usd-currency-uuid",
"exchange_rate": "1"
}
]
}
```
Optional fields: `reference`, `contact`, `project`, `document` (file UUID for receipt/invoice attachment), `metadata` (JSON).
### Update journal (replaces lines)
When you include `lines_data` in a PUT request, all existing lines are replaced:
```
PUT /finance/api/journals/{id}/
{
"entity": "uuid",
"date": "2026-03-10",
"description": "Updated description",
"lines_data": [...]
}
```
Omit `lines_data` to update journal fields without touching lines.
### Post a journal
```
POST /finance/api/journals/{id}/post_entry/
```
Changes status from `draft` to `posted`. Only posted journals appear in reports.
### Get / Delete
```
GET /finance/api/journals/{id}/
DELETE /finance/api/journals/{id}/
```
---
## Reports
All report endpoints return JSON. They share common filter parameters:
| Param | Description |
|-------|-------------|
| `entity` | Filter by entity UUID |
| `date_from` | Start date (YYYY-MM-DD) |
| `date_to` | End date (YYYY-MM-DD) |
| `as_of` | Point-in-time date (balance sheet, trial balance) |
### Profit & Loss
```
GET /finance/api/journals/report_pnl/
```
Returns income and expense accounts with totals:
```json
{
"income_items": [
{"account_id": "uuid", "code": "4100", "name": "Sales Revenue", "amount": "5000"}
],
"expense_items": [
{"account_id": "uuid", "code": "5100", "name": "Rent", "amount": "1200"}
],
"total_income": "5000",
"total_expenses": "1200",
"net_income": "3800"
}
```
### Balance Sheet
```
GET /finance/api/journals/report_balance_sheet/
```
Returns assets, liabilities, equity, and retained earnings:
```json
{
"asset_items": [...],
"liability_items": [...],
"equity_items": [...],
"total_assets": "10000",
"total_liabilities": "3000",
"total_equity": "5000",
"retained_earnings": "2000",
"total_equity_with_retained": "7000",
"total_liabilities_equity": "10000",
"is_balanced": true
}
```
### Cash Flow
```
GET /finance/api/journals/report_cash_flow/
```
Monthly breakdown of cash movements through asset accounts (cash, bank, etc.):
```json
{
"months": [
{"month": "2026-03-01", "cash_in": "5000", "cash_out": "1200", "net": "3800"}
],
"total_in": "5000",
"total_out": "1200",
"total_net": "3800"
}
```
Note: Only tracks asset account movements. Credit card payments (liability accounts) don't appear here.
### Trial Balance
```
GET /finance/api/journals/report_trial_balance/
```
Every account with total debits and credits:
```json
{
"accounts": [
{"account_id": "uuid", "code": "1010", "name": "Cash", "account_type": "asset", "total_debit": "5000", "total_credit": "1200"}
],
"grand_debit": "6200",
"grand_credit": "6200",
"is_balanced": true
}
```
---
## Summary
Quick income/expenses/net for dashboards:
```
GET /finance/api/journals/summary/?entity_id={uuid}&date_from=2026-01-01&date_to=2026-12-31
```
```json
{
"total_income": "5000",
"total_expenses": "1200",
"net": "3800"
}
```
---
## Currencies
System currencies (USD, EUR, BTC, XAU, etc.) are read-only:
```
GET /finance/api/currencies/
GET /finance/api/currencies/?search=bitcoin
```
---
## MCP Integration
All finance operations are also available through MCP tools:
- `create_finance_entity` — create a new entity
- `create_finance_account` — add an account
- `create_journal_with_lines` — create a journal entry with balanced lines
- `list_finance_entities` — list your entities
- `list_finance_accounts` — list accounts (filter by entity/type)
- `list_finance_entries` — list journal entries
- `get_finance_entity` — entity details with account summary
- `get_finance_summary` — income/expense/net totals
- `post_finance_entry` — post a draft journal
- `setup_finance_accounts` — create default chart of accounts
Example: "Create a journal entry for $50 office supplies paid by credit card" works naturally through any MCP-compatible AI assistant.
---
## File Attachments
Attach receipts or invoices to journal entries using the `document` field:
1. Upload a file via `POST /api/files/upload/`
2. Pass the returned file UUID as `document` when creating a journal
The attachment appears on the journal detail page with a direct link to the file.