# Scenarios

> Pick a named synthetic patient to test a specific record shape or failure.

Each scenario is a synthetic patient with a known record or a scripted behavior. Use them with the [demo API](/docs/get-started/demo-api), or with a sandbox key through `simulate`. The [Quickstart](/docs/get-started/quickstart) shows how to create the session and wait for `simulation.state`.

```bash
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](/docs/testing/conformance). |
| `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`.