Production access is free and self-serve with an account. · Synthetic demo · no account needed
Connect
One hosted link takes a patient from provider search to a signed consent receipt.
Your backend creates one Connect session and sends the patient to its hosted URL. FinchNode handles provider search, sign-in on the health system’s own SMART on FHIR page, the import, and a separate sharing decision, then exposes an app-scoped pseudonymous subject once the session is completed.
Built for: Teams that need patient-authorized records without building per-vendor OAuth.
Base URL: https://api.finchnode.com/api/v1
Authentication: Send an app-scoped key as a Bearer token from your backend: Authorization: Bearer ck_test_... for sandbox keys, which read only sandbox connections, or Authorization: Bearer ck_live_... for live keys, which read only production connections and which eligible applications create in the self-service console. Keys are hashed at rest, revocable, and must never be embedded in browser or mobile code.
Create a free account to get sandbox keys: https://finchnode.com/signup
https://api.finchnode.com/api/mcpexport FINCHNODE_API_KEY=ck_test_...curl -X POST https://api.finchnode.com/api/v1/connect/sessions -H "Authorization: Bearer $FINCHNODE_API_KEY" -H "Idempotency-Key: <a fresh UUID>" -H "Content-Type: application/json" -d '{"returnUrl":"http://localhost:3000/return"}'Sandbox keys start with ck_test_ and are created with your free account. A completed session exposes the app-scoped subject, and GET /users lists the app’s subjects in cursor pages; follow nextCursor while hasMore is true.
Expected response: 201 with a connect_session: an id (cs_ followed by 20 hex characters), status, categories, syncMode, durationDays, a sync object, subject null until completion, and a single-use url that expires after 24 hours. Send the patient to url.
Three ways in for a coding agent: connect the MCP endpoint below, load the OpenAPI document (https://finchnode.com/openapi.yaml), or fetch this page as markdown (https://finchnode.com/products/hosted-connect.md). https://finchnode.com/llms.txt lists every product’s markdown twin.
https://api.finchnode.com/api/mcpclaude mcp add --scope project --transport http finchnode https://api.finchnode.com/api/mcp --header 'Authorization: Bearer ${FINCHNODE_API_KEY}'Claude Code writes this server to the project's .mcp.json, which is meant to be checked into version control and shared with the project, and expands ${FINCHNODE_API_KEY} when it connects, so the file never holds the key: set FINCHNODE_API_KEY in the shell that runs Claude Code.
codex mcp add finchnode --url https://api.finchnode.com/api/mcp --bearer-token-env-var FINCHNODE_API_KEY{
"mcpServers": {
"finchnode": {
"url": "https://api.finchnode.com/api/mcp",
"headers": {
"Authorization": "Bearer ${env:FINCHNODE_API_KEY}"
}
}
}
}Request the narrowest categories the displayed purpose needs; they must be within the app allowlist. Set syncMode to one-time or continuous, durationDays from 1 to 730 (default 365), an opaque externalId with no names, email addresses, or health data, and a returnUrl. Reusing an Idempotency-Key with the identical body recovers the original session and sets Idempotent-Replayed: true; a different body returns 409 idempotency_conflict.
curl -X POST https://api.finchnode.com/api/v1/connect/sessions -H "Authorization: Bearer $FINCHNODE_API_KEY" -H "Idempotency-Key: connect-account-123-v1" -H "Content-Type: application/json" -d '{"externalId":"account_123","categories":["demographics","medications","labs"],"syncMode":"continuous","durationDays":365,"returnUrl":"https://app.example.com/settings/health"}'The url in the response is single-use and expires after 24 hours. The patient finds their provider, signs in on the provider or EHR authorization page, approves access, and separately consents to share the requested data with your application. Hospital usernames and passwords do not pass through FinchNode.
GET {url} # the single-use session url from the 201 response, opened in the patient’s browserUse the session from step 1 (its id is SESSION_ID) instead of creating another; created with a sandbox key, it is a sandbox session. A sandbox session needs no real patient: either open its hosted url yourself and choose one of the FinchNode Scenario Sandbox organizations listed above the search, which connects a synthetic source without a hospital sign-in (the account and consent steps are unchanged), or POST /connect/sessions/{sessionId}/simulate with a scenario and poll the session until simulation.state is completed. Either way the completed session exposes the subject (its id is SUBJECT), and GET /users lists the app’s subjects.
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":"baseline-adult"}'Poll the session or wait for the consent.granted webhook. The sync object reports queued, syncing, then complete, partial, failed, or reauthorization_required, with available and missing categories. Only status: completed exposes subject, and only after the patient’s sharing consent.
curl https://api.finchnode.com/api/v1/connect/sessions/$SESSION_ID -H "Authorization: Bearer $FINCHNODE_API_KEY"An incomplete session can be closed. Repeating the request is safe.
curl -X POST https://api.finchnode.com/api/v1/connect/sessions/$SESSION_ID/cancel -H "Authorization: Bearer $FINCHNODE_API_KEY"| Method | Path | OpenAPI operationId |
|---|---|---|
| POST | https://api.finchnode.com/api/v1/connect/sessions | createConnectSession |
| GET | https://api.finchnode.com/api/v1/connect/sessions/{sessionId} | getConnectSession |
| POST | https://api.finchnode.com/api/v1/connect/sessions/{sessionId}/cancel | cancelConnectSession |
Your application creates a Connect session and sends the patient to a hosted flow. The patient finds their provider, signs in on the provider or EHR authorization page, approves access, and separately consents to share the requested data with your application.
No. Patients enter their credentials on the hospital, payer, or EHR authorization page. Hospital usernames and passwords do not pass through FinchNode.
No. Your product creates one FinchNode Connect session. FinchNode’s hosted flow handles provider search, source authorization, connection state, and the patient consent experience for supported systems.
Yes, with the same Idempotency-Key and the identical body: FinchNode returns the original session and sets Idempotent-Replayed: true. Reusing the key with a different body returns 409 idempotency_conflict.
FinchNode has 17 EHR and payer integrations. Record availability depends on the organization a patient selects, the scopes it grants, and the patient authorization behind each connection.