# Liquify export — Reports

English field reference for the Reports JSON download (current period). This file is for your own analysis tools; Liquify does not import it back.

Nested `boxes`, `balances`, and `investmentHoldings` are curated to today’s plan boxes and Investments groups. Day-level KPI numbers stay as captured on that date.

## Top-level keys

| Key             | Meaning                                             |
| --------------- | --------------------------------------------------- |
| `schemaVersion` | Reports download format version.                    |
| `exportedAt`    | UTC timestamp when the file was written (ISO-8601). |
| `budgetId`      | Budget id.                                          |
| `budgetName`    | Budget display name.                                |
| `period`        | Period code (for example month / week selection).   |
| `periodLabel`   | Human-readable period label.                        |
| `baseCurrency`  | Budget base currency.                               |
| `snapshots`     | Array of daily snapshot objects.                    |

## Snapshot (`snapshots[]`) — day KPIs

| Key                                             | Meaning                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `date`                                          | Snapshot calendar date.                                                                           |
| `capturedAt`                                    | When the snapshot was captured.                                                                   |
| `baseCurrency`                                  | Currency for totals.                                                                              |
| `schemaVersion`                                 | Snapshot storage version (may differ from outer download version).                                |
| `monthlyNetIncome`                              | Planned monthly net income.                                                                       |
| `incomeMinusPlanned`                            | Income minus planned spend for the day (Reports KPI). Not the same as budget `unallocatedAmount`. |
| `plannedExpenseTotal`                           | Total planned expenses.                                                                           |
| `needsAmount` / `wantsAmount` / `savingsAmount` | Category amounts.                                                                                 |
| `needsPercent` / `wantsPercent`                 | Share of plan by category.                                                                        |
| `savingsShareOfPlan`                            | Savings as a share of the plan.                                                                   |
| `savingsShareOfIncome`                          | Savings as a share of income.                                                                     |
| `debitLiquidityTotal`                           | Liquidity in payment (debit) accounts.                                                            |
| `creditBalanceTotal`                            | Credit balances total.                                                                            |
| `creditLinkedPaymentTotal`                      | Payment-side balances linked to credit boxes.                                                     |
| `creditLinkedDebtTotal`                         | Debt-side balances linked to credit boxes.                                                        |
| `underfundedBoxCount`                           | Count of underfunded boxes.                                                                       |
| `alertConditionCounts`                          | Optional map of alert condition counts.                                                           |
| `boxes`                                         | Curated box rows for that day.                                                                    |
| `balances`                                      | Curated account balance rows.                                                                     |
| `investmentHoldings`                            | Curated investment holding rows (not nested key `investments`).                                   |

## Box row (`snapshots[].boxes[]`)

| Key                      | Meaning                                            |
| ------------------------ | -------------------------------------------------- |
| `boxId`                  | Expense box id.                                    |
| `name`                   | Box name.                                          |
| `category`               | `NEEDS`, `WANTS`, or `SAVINGS`.                    |
| `paymentMode`            | `account` or `creditCard`.                         |
| `planAmount`             | Planned amount.                                    |
| `goalAmount`             | Optional goal.                                     |
| `expectedInAccountToday` | How much should be in the linked account that day. |
| `linkedBalance`          | Linked account balance.                            |
| `balanceVsExpected`      | Linked balance minus expected.                     |
| `linked`                 | Whether the box has a linked account.              |
| `alertConditions`        | Alert flags for the box.                           |

## Balance row (`snapshots[].balances[]`)

| Key                      | Meaning                                           |
| ------------------------ | ------------------------------------------------- |
| `accountLinkId`          | AccountLink id (join key with Accounts download). |
| `boxId`                  | Linked box id.                                    |
| `kind`                   | `manual` or `bank`.                               |
| `accountKind`            | Account type (for example checking).              |
| `slot`                   | `payment` or `credit`.                            |
| `balance`                | Balance in account currency.                      |
| `currency`               | Account currency.                                 |
| `balanceInBase`          | Balance converted to budget currency.             |
| `syncedAt` / `updatedAt` | Optional timestamps.                              |
| `stale`                  | Whether the balance is considered stale.          |

## Investment row (`snapshots[].investmentHoldings[]`)

| Key                                      | Meaning                      |
| ---------------------------------------- | ---------------------------- |
| `investmentId`                           | Holding id.                  |
| `name`                                   | Display name.                |
| `kind`                                   | `manual` or `bank`.          |
| `groupKey`                               | Investment group key.        |
| `groupName`                              | Optional group display name. |
| `balance` / `currency` / `balanceInBase` | Value and conversion.        |
| `syncedAt` / `updatedAt` / `stale`       | Sync metadata.               |

## Related guides

- [Plan, backup, and share](./plan.md)
- [Accounts](./accounts.md)
- [Investments](./investments.md)