Quickstart: your first referral in 10 minutes

This walks you from a cold signup to a delivered referral and a received webhook, using only the sandbox and public HTTP endpoints — no insider knowledge, nothing that isn’t documented on this site.

1. Sign up

curl -X POST https://api.sandbox.railflo.com/v1/auth/signup \
  -H 'content-type: application/json' \
  -d '{"orgName": "Acme Clinic", "email": "you@example.com", "password": "a genuinely long passphrase"}'

You get back a tenant_id, user_id, and a totp_provisioning_uri — scan that into an authenticator app (Google Authenticator, 1Password, etc.).

Your tenant is auto-provisioned on the sandbox with a facility, a practitioner, and 50 synthetic patients (3 of them magic values) — you don’t need to create any of that yourself.

2. Finish enrolment and log in

curl -X POST https://api.sandbox.railflo.com/v1/auth/totp/verify \
  -H 'content-type: application/json' \
  -d '{"tenant_id": "org_...", "user_id": "usr_...", "code": "123456"}'

This returns a set of one-time recovery codes — save them. Then log in:

curl -X POST https://api.sandbox.railflo.com/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email": "you@example.com", "password": "a genuinely long passphrase"}' \
  -c cookies.txt

A login always needs a second TOTP step — see Authentication & keys for the full session model.

3. Create your first API key

API keys are minted from Console, not from the public API itself (POST /v1/api_keys needs an existing key to call it — that’s the point). Log into console.railflo.com (or, sandboxed, console.sandbox.railflo.com) with the account from step 1, go to Settings → API keys, and create a test-mode key. Copy the secret now — it’s shown exactly once.

4. Create a patient

curl -X POST https://api.sandbox.railflo.com/v1/patients \
  -H "Authorization: Bearer railflo_sk_test_..." \
  -H 'content-type: application/json' \
  -d '{
    "family_name": "Walsh",
    "given_name": "Aoife",
    "dob": "1990-06-15",
    "identifiers": [{ "type": "MRN", "value": "ACME-001" }]
  }'

This is your first successful API call.

5. Register a webhook endpoint

curl -X POST https://api.sandbox.railflo.com/v1/webhook_endpoints \
  -H "Authorization: Bearer railflo_sk_test_..." \
  -H 'content-type: application/json' \
  -d '{"url": "https://webhook.site/your-unique-url", "enabled_events": ["exchange.created", "exchange.delivered"]}'

The response includes a whsec_... signing secret — shown exactly once. See Webhooks for verifying signatures.

6. Send a referral

curl -X POST https://api.sandbox.railflo.com/v1/referrals \
  -H "Authorization: Bearer railflo_sk_test_..." \
  -H 'content-type: application/json' \
  -d '{
    "sender": { "practitioner_id": "prac_..." },
    "recipient": { "kind": "railflo_org", "org_id": "org_..." },
    "patient": "pat_...",
    "purpose_of_use": "treatment"
  }'

Use your own facility’s prac_... id (visible from Console → Settings → Organisation) and, on the sandbox, run the inbound_referral scenario script first to get a real org_... to send to.

7. Watch the webhook arrive

Your registered endpoint receives an exchange.created event immediately, and exchange.delivered once routing completes — see Exchanges for the full lifecycle and state diagram.

That’s the whole loop: signup → key → patient → webhook → referral → delivery.