Core concepts
A quick tour of the objects you work with in Rail.
The record is assembled from many sources
A single patient's data is scattered across many places — different clinics, payers, labs, pharmacies, and health information exchanges. Rail connects to each, pulls the data, and assembles one normalized record. You integrate once and get everything back through the same API.
Sources
A source is something connectable: an EHR, a health plan, a lab, a pharmacy, a health information exchange, or a device. The source catalog tells you what's available and how each connects.
curl https://rail.to/api/v1/sources -H "Authorization: Bearer sk_sandbox_rail_democare"
Connections
A connection is one patient's authorized link to one source. A patient
usually has several — one per place that holds their data. Each connection tracks
its own status, so you always know whether a source is active, still syncing,
or needs the patient to re-authorize.
The patient record
Above the connections sits the patient — the single, deduplicated record Rail assembles from everything the patient connected. This is where Rail does its real work:
- Deduplication. The same medication reported by the prescriber, the pharmacy, and the payer becomes one entry.
- Provenance. Every fact carries the source(s) it came from — nothing is a black box.
- Normalization. Codes from different systems (for example, a diagnosis coded one way by a clinic and another by a payer) are reconciled to one concept, with the original codes preserved.
Members
A member is the person who authorizes access. Usually the member is the patient. But the model also supports a member acting for someone else — a parent authorizing for a child, or a caregiver for a dependent — without changing your integration.
Keys and tokens
Rail uses two kinds of credential:
| Credential | Prefix | Use |
|---|---|---|
| App key | sk_ (secret) / rk_ (restricted) | Server-side setup and management — creating connect sessions, exchanging tokens, listing sources. |
| Patient access token | ptok_ | Reading one patient's record. Scoped to exactly what that patient granted. |
A publishable key (pk_) is used only to launch Rail Connect on the client;
it can't read data. Keep secret keys and patient tokens on your server.
A good default: hold each patient's ptok_ for reads, and reach for restricted
keys (rk_) — scoped to just the products you use — anywhere you need an app key.
How a patient connects
The authorization flow is three short steps:
- Create a connect session (server) → get a session token.
- Launch Rail Connect (client) with that token. The patient signs in to their provider, payer, or other source and chooses what to share. On success you receive a short-lived public token.
- Exchange the public token (server) → get a long-lived patient access token scoped to what they granted.
See the Quickstart for the calls, and Products & scopes for what you can request.