Understanding your financial data

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

balance_available may be null for accounts that don’t report available balances, such as some investment accounts.

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)

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.

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.

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.

Getting Started

Reference

SDKs

Concepts

Webhooks

Use Cases

Tools

Resources

Understanding your financial data

Accounts

Transactions

Amount and direction

Dates

Categories

Merchant

Recurring streams

Scores

Goals

Income

Investments

Resource relationships

​Accounts

​Transactions

​Amount and direction

​Dates

​Categories

​Merchant

​Recurring streams

​Scores

​Goals

​Income

​Investments

​Resource relationships

Accounts

Transactions

Amount and direction

Dates

Categories

Merchant

Recurring streams

Scores

Goals

Income

Investments

Resource relationships