docs

Quickstart

Rail gives you one API for a patient's complete health record — claims, conditions, medications, labs, and more — normalized to FHIR R4 and deduplicated across sources. This guide takes you from zero to a record in four calls.

Try it live. Every example here runs against the built-in sandbox, which returns realistic synthetic data (no real patient information). Open the API Reference to send these requests from your browser — the sandbox key is pre-filled.

1. Authenticate

All requests use a bearer credential:

Authorization: Bearer <key-or-token>

In the sandbox, use the demo app key for setup calls:

sk_sandbox_rail_democare

2. Create a connect session

A patient authorizes access through Rail Connect, a drop-in flow. Your server creates a session that tells Connect which products you want, and gets back a session token to launch the UI.

curl -X POST https://rail.to/api/v1/connect/sessions \
  -H "Authorization: Bearer sk_sandbox_rail_democare" \
  -H "Content-Type: application/json" \
  -d '{ "products": ["clinical", "labs", "medications"] }'

3. Exchange the public token

When the patient finishes authorizing, Rail Connect hands your client a short-lived public token. Exchange it on your server for a long-lived patient access token scoped to exactly what the patient granted.

curl -X POST https://rail.to/api/v1/connect/exchange \
  -H "Authorization: Bearer sk_sandbox_rail_democare" \
  -H "Content-Type: application/json" \
  -d '{ "public_token": "pub_sandbox_olivia_martin" }'

{
  "patient": "pat_olivia_martin",
  "access_token": "ptok_sandbox_olivia_martin",
  "granted_scopes": ["patient/Condition.rs", "patient/Observation.rs?category=laboratory", "…"]
}

Store the access_token securely on your server — it's the credential you use to read this patient's record.

4. Read the record

curl https://rail.to/api/v1/patients/pat_olivia_martin/record \
  -H "Authorization: Bearer ptok_sandbox_olivia_martin"

You get back a single, deduplicated record, grouped by resource type. The same diagnosis reported by a clinic, a lab, and a payer appears once, with every source preserved:

{
  "object": "record",
  "patient": "pat_olivia_martin",
  "resources": {
    "Condition": [ /* … */ ],
    "Observation": [ /* labs + vitals */ ],
    "MedicationRequest": [ /* … */ ],
    "ExplanationOfBenefit": [ /* … */ ]
  }
}

Next steps