How Connect works

The short version

1. Your server creates a session and gets back a url.
2. You send the patient there.
3. The patient picks a health system and signs in on that health system's own page. FinchNode imports their records.
4. The first time, the patient creates a FinchNode account and verifies its email in the same browser.
5. They approve sharing with your app, and the session completes with a subject.
6. Your server reads the records.

FinchNode hosts the Connect flow, and the health system hosts its own sign-in page. You never handle the patient's portal password.

Two consents

The patient agrees twice, and the two agreements are separate:

• Collection. At the start, they let FinchNode import records from the health system they pick.
• Sharing. After import, they review the categories that arrived, the sharing terms, and any warnings, then approve sharing with your app.

Your app reads only what the sharing consent covers. The patient can revoke it at any time. See Consent, revocation, and deletion.

Session statuses

Status	Means
pending	Created. The patient hasn't agreed to collection yet.
collect-consented	They agreed to collection and are choosing a health system.
system-selected	They picked one. Sign-in, import, account setup, or sharing approval is still to come.
completed	They approved sharing. subject is set.
canceled	They or your server canceled it.
expired	Nobody finished it within 24 hours.
abandoned, failed	Reserved in the schema. Treat either as finished without sharing.

status follows the flow, and sync.status follows the import, so read both. A completed session stays completed even after the patient later revokes sharing.

One patient per link

A session belongs to the first patient who starts it. They can reopen the link to pick up where they left off until it expires 24 hours after you created it. Anyone else who opens it is turned away. Create a new session for each attempt.

What your server does

• Create the session with the categories you need. See Create a session.
• Learn the outcome. See After the patient connects.
• Read records for that subject. See Read and paginate.

Try it without a patient

With a sandbox key, POST /connect/sessions/{sessionId}/simulate with {"scenario": "baseline-adult"} completes a session with a synthetic patient. Poll simulation.state, not status. The Quickstart walks through it.