Data freshness and sync model

Yoshi syncs data from your connected financial institutions automatically. This page explains the sync model, how to interpret freshness signals, and how to build UIs that handle stale data gracefully.

How syncing works

When you connect a financial account, Yoshi begins syncing data from that institution on a recurring schedule:

Data type	Typical sync frequency	Notes
Transactions	Every few hours	New and updated transactions are pulled in each sync
Balances	With each sync	Updated alongside transactions
Investment holdings	Daily	Some institutions update less frequently
Recurring streams	After each transaction sync	Patterns are re-analyzed as new data arrives
Scores	Daily	Recalculated once per day based on the latest data

Sync frequency varies by institution. Some provide near real-time data, while others update once per business day.

The `as_of` timestamp

Each account includes an as_of field that tells you when its data was last refreshed:

{
  "id": "acc_abc123",
  "name": "Chase Checking (...4521)",
  "balance_current": 4523.17,
  "as_of": "2026-04-10T08:30:00.000Z"
}

Use as_of to show users when their data was last updated:

const account = accounts[0];
const lastSync = new Date(account.as_of);
const minutesAgo = Math.round((Date.now() - lastSync.getTime()) / 60000);

if (minutesAgo > 60) {
  console.log(`Balance may be stale (last updated ${minutesAgo} minutes ago)`);
}

Use webhooks instead of polling

Rather than polling endpoints on a timer, subscribe to webhook events for real-time updates:

Event	Fires when
`transaction.created`	New transactions are synced
`transaction.updated`	Existing transactions change (e.g., pending → posted)
`balance.updated`	Account balance changes
`investment.updated`	Investment holdings are refreshed
`score.updated`	Financial health scores are recalculated

curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer yoshi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "filter_types": ["transaction.created", "balance.updated"]
  }'

See the Webhooks guide for full setup instructions.

Handle stale data in your UI

Financial data may be minutes to hours old depending on the institution. Here are patterns for communicating freshness to users: Show the last sync time:

Chase Checking: $4,523.17 · Updated 2 hours ago

Flag potentially stale data:

const STALE_THRESHOLD_MS = 4 * 60 * 60 * 1000; // 4 hours
const isStale = Date.now() - new Date(account.as_of).getTime() > STALE_THRESHOLD_MS;

Don’t promise real-time accuracy. Balances and transactions reflect the most recent sync, not the current moment. A user may have made a purchase minutes ago that hasn’t synced yet.

Pending transactions

Transactions with pending: true are authorized but not yet settled. They can:

Change amount (tips, holds)
Change date
Disappear entirely (voided authorizations)

Once a transaction posts (pending: false), it’s final. Always use the transaction id for tracking — don’t match on amount or description, which can change.

Data freshness and sync model

How syncing works

The `as_of` timestamp

Use webhooks instead of polling

Handle stale data in your UI

Pending transactions

What’s next

Webhooks

Best practices

​How syncing works

​The as_of timestamp

​Use webhooks instead of polling

​Handle stale data in your UI

​Pending transactions

​What’s next

Webhooks

Best practices

How syncing works

The `as_of` timestamp

Use webhooks instead of polling

Handle stale data in your UI

Pending transactions

What’s next