Scenarios

Each scenario is a synthetic patient with a known record or a scripted behavior. Use them with the demo API, or with a sandbox key through simulate. The Quickstart shows how to create the session and wait for simulation.state.

curl -X POST "https://api.finchnode.com/api/v1/connect/sessions/$SESSION_ID/simulate" \
  -H "Authorization: Bearer $FINCHNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario": "polypharmacy-senior"}'

Record scenarios

Use these to test how your app shows real-looking records.

Scenario	Use it to test
baseline-adult	Type 2 diabetes and hypertension: two medications, two labs, one blood pressure, one allergy, two immunizations. The default.
polypharmacy-senior	A long record: fourteen active medications, forty labs, thirty vitals. Good for pagination.
pediatric-asthma	A child with growth measurements, inhalers, and a partial immunization history.
multi-source-overlap	The same patient at two health systems, with duplicate records under each.
sparse-record	Demographics and one visit; most categories empty.
messy-coding	Free-text medications, missing values, and odd codes.

Behavior scenarios

Use these to test your error handling.

Scenario	What happens
rate-limited	In the demo API, reads return 429 with Retry-After in alternating two-second windows. Simulated, it's an ordinary small record; test retries with a key in a conformance run.
consent-revoked	Every record read returns 410 consent_inactive.
consent-partial	Only medications and allergies are shared; other categories return 403 consent_scope_exceeded.
source-unavailable	One of two sources fails every sync, so reads are partial with a source_unavailable warning.

Session scenarios

connect-cancelled and connect-failed end a Connect session without a patient. They run only in the demo API; simulate returns 400 invalid_scenario for them.

Limits

• Sandbox patients are synthetic. Their records never come from a real health system.
• An application holds up to 25 active synthetic patients by default. Each becomes eligible for purge 7 days after it's created.
• For multi-source-overlap, source-unavailable, and consent-revoked, poll simulation.state rather than status.
• consent-partial grants only medications and allergies. If your session asked for none of those, simulate returns 400 invalid_categories.