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

# Understanding your financial data

> Reference for Yoshi resources: accounts, transactions, scores, recurring streams, goals, income, and investments, plus key fields and relationships.

Yoshi organizes your financial data into a set of core resources. This page explains what each one represents and how to interpret key fields.

## Accounts

An account represents a single financial account — a checking account, savings account, credit card, investment account, or loan. Each account belongs to a financial institution and has a current balance.

| Field | Description |
| - | - |
| `type` | Top-level category: `depository`, `credit`, `investment`, `loan` |
| `subtype` | More specific: `checking`, `savings`, `credit card`, `401k`, `mortgage`, etc. |
| `balance_current` | Most recent balance as reported by the institution |
| `balance_available` | Available to spend or withdraw (may differ from current for credit/checking) |
| `balance_limit` | Credit limit (credit accounts only) |
| `as_of` | When the balance was last refreshed |
| `hidden` | Whether the user has hidden this account from their dashboard |

<Info>
  `balance_available` may be `null` for accounts that don't report available balances, such as some investment accounts.
</Info>

## Transactions

A transaction is a single financial event — a purchase, payment, deposit, transfer, or fee. Transactions belong to an account and include merchant information, categorization, and timing data.

### Amount and direction

| Field | Description |
| - | - |
| `amount` | Signed amount. Negative for outflows, positive for inflows. |
| `amount_absolute` | Unsigned amount (always positive). Use this for display. |
| `cash_flow_direction` | `"outflow"` (you spent money) or `"inflow"` (you received money) |

<Warning>
  The sign of `amount` follows accounting convention — a credit card purchase appears as a positive value on a credit account but as an outflow in `cash_flow_direction`. Always use `cash_flow_direction` for logic and `amount_absolute` for display.
</Warning>

### Dates

| Field | Description |
| - | - |
| `date_posted` | When the transaction settled (final). Use this for reporting. |
| `date_authorized` | When the transaction was first authorized. May be `null`. |
| `pending` | `true` if the transaction hasn't settled yet |

Pending transactions may change amount, date, or disappear entirely before posting. Use the transaction `id` for deduplication — don't match on amount or description.

### Categories

| Field | Description |
| - | - |
| `category_label` | Human-readable label, e.g. "Groceries" |
| `category_tier1` | Top-level category, e.g. "Food & Drink" |
| `category_tier2` | Sub-category, e.g. "Groceries". May be `null`. |

### Merchant

| Field | Description |
| - | - |
| `counterparty_name` | Cleaned merchant name, e.g. "Whole Foods" |
| `counterparty_logo_url` | Merchant logo URL. May be `null`. |
| `original_description` | Raw transaction description from the institution |

## Recurring streams

A recurring stream is a detected pattern of repeated transactions — subscriptions, monthly bills, or regular income. Yoshi identifies these automatically from transaction history.

| Field | Description |
| - | - |
| `direction` | `"outflow"` (bill/subscription) or `"inflow"` (income) |
| `frequency` | Detected pattern: `monthly`, `weekly`, `biweekly`, `annual`, etc. |
| `status` | `"active"` or `"inactive"` (stream appears to have stopped) |
| `average_amount` | Typical amount based on recent occurrences |
| `predicted_next_date` | When the next occurrence is expected |

## Scores

Yoshi calculates four financial health scores, each on a 0–100 scale:

| Score | What it measures |
| - | - |
| `yoshi` | Composite overall financial health |
| `recovery` | How quickly you recover from spending dips |
| `capacity` | Available financial cushion relative to obligations |
| `baseline` | Consistency and stability of your financial patterns |

Scores are recalculated daily. The `observation_date` field indicates when the scores were last computed.

## Goals

A goal represents a financial objective the user is working toward:

| Field | Description |
| - | - |
| `goal_type` | What kind of goal: `savings`, `debt_payoff`, etc. |
| `status` | `active`, `paused`, or `completed` |
| `target_amount` | Dollar amount the user is trying to reach |
| `current_value` | Progress toward the target |
| `target_date` | When the user wants to reach the goal |

## Income

The income resource provides an analysis of the user's income sources:

| Field | Description |
| - | - |
| `total_income_annual` | Estimated annual income across all sources |
| `total_income_monthly` | Estimated monthly income |
| `income_sources` | Array of detected income streams |
| `income_sources[].confidence` | `high`, `medium`, or `low` — how confident the detection is |

## Investments

Investment data shows the user's holdings grouped by asset class:

| Field | Description |
| - | - |
| `symbol` | Ticker symbol, e.g. "AAPL" |
| `current_value` | Market value of the position |
| `quantity` | Number of shares held |
| `cost_basis_total` | Original purchase cost |
| `total_gain_loss` | Unrealized gain or loss |
| `day_change` | Change in value today |
| `percent_of_account` | Position as a percentage of the total account (0–100) |

## Resource relationships

```
User
├── Accounts
│   ├── Transactions
│   └── Balance history
├── Recurring streams
├── Scores
├── Goals
├── Income sources
└── Investments (holdings by account)
```

Every resource is scoped to the authenticated user. You can only access your own data — there is no cross-user access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.