Freshness, partial and stale records

Health systems don't always return everything, and syncs fail. Every snapshot and category page carries meta so you can say what you have.

Read the metadata

Field	Meaning
syncStatus	complete, partial, or not_started.
dataAsOf	The oldest source watermark among the sources in this response.
lastSuccessfulSyncAt	The latest finish time among each source's most recent complete or partial sync.
availableCategories	Categories where at least one source returned data in its last usable sync.
missingCategories	Categories FinchNode couldn't read.
warnings	Source- or category-level problems, each with a code and message.

A category counts as available when any of its resource types came back, so a partly read category may not appear in missingCategories. Check warnings too.

Before you say "no records"

An empty category means "none on file" only when:

• syncStatus is complete,
• the category is in availableCategories, and
• no warning names it.

Otherwise say it couldn't be loaded. A source that hasn't synced yet returns empty data with no warnings and syncStatus: "not_started".

When a source fails

If a source synced before and its latest sync failed, syncStatus is partial and warnings includes something like this (synthetic):

{
  "code": "source_unavailable",
  "source": "northstar-health",
  "message": "The latest sync from this source did not complete. Records shown are from its last successful sync.",
  "retryable": true
}

Show those records with their age, from dataAsOf. A sync that failed partway may still have applied some changes before it stopped.

Continuous sync

With continuous sync, FinchNode re-imports every 6 hours by default. A share gets it only when all three hold:

1. Your application is set to continuous.
2. The patient opted in on the consent screen.
3. The health system allows ongoing access.

Otherwise it's one-time. The receipt's syncMode says which you got.

Sync webhooks

These arrive only for continuous shares, after a scheduled re-import. The first import doesn't send them; consent.granted covers it.

Event	When
sync.completed	A re-import finished with everything it asked for.
sync.partial	A re-import finished with something missing.
sync.failed	A re-import failed. data.code and data.retryable say why and whether it will try again.
records.updated	A re-import changed or deleted records.

If a failed refresh needs the patient to sign in again, they reconnect from their FinchNode account.