Cura EHR Integration Guide (FHIR R4 + SMART)

At a glance

• Standards: FHIR R4 (REST), SMART on FHIR (OAuth2), optional HL7 v2 bridge
• Auth: Client Credentials (system) or SMART (user authorization)
• Sync: Pull demographics/records; Push consented notes/codes; org- and consent-scoped
• Security: TLS, org isolation, full audit, least-privilege scopes

Requirements

• FHIR Base URL (e.g., https://ehr.example.com/fhir)
• OAuth token endpoint; for SMART also authorization endpoint
• Client credentials (or registered SMART client)
• Approved scopes (patient read/write as needed)

Auth modes

Data model mapping (defaults)

What syncs

• EHR → Cura: patient demographics, allergies, medications, observations, encounters
• Cura → EHR (with consent): encounter notes, diagnosis/procedure codes, consent events
• Everything is org- and consent-scoped with full audit logs

Onboarding checklist

1. Confirm FHIR base URL and OAuth endpoints (token and, for SMART, authorization)
2. Register a client (Client Credentials) or a SMART confidential client
3. Approve minimum scopes needed; avoid broad system-wide scopes
4. Decide patient matching strategy (MRN, national id, or mapped cura id)
5. Run connectivity test from Cura (metadata and token)
6. Perform a pilot sync in a sandbox org; validate 10 patients
7. Enable schedule and monitor audit logs for 72 hours

Security and networking

• TLS required end-to-end; pin to the hospital CA if policy requires
• Allowlist Cura egress IPs to reach the FHIR API if your network is closed
• Use org-specific credentials; rotate keys every 90 days
• Enable least-privilege scopes and limit resource types if supported

Sync policies

• Read window: incremental by lastUpdated, with backfill on first run
• Write policy: only with active consent and role-based authorization
• Conflict handling: prefer most recent by timestamp; flag ties for review
• Retry: exponential backoff, capped attempts, dead-letter queue for ops

Error handling

• 401/403: refresh tokens or reduce scopes; verify client registration
• 429: respect Retry-After; reduce page size and frequency
• 5xx: automatic retry with jitter; alert after threshold
• Data validation: reject malformed resources; record reason in audit

Setup steps (Cura UI)

1. Go to Provider → EHR Sync
2. Enter FHIR Base URL, choose Auth Method (Client Credentials or SMART)
3. Provide OAuth endpoints and scopes (SMART) or client credentials
4. Click “Test Endpoints” then “Connect” and “Sync Now”
5. Review mapping preview and audit logs; enable schedule

Security & compliance

• TLS 1.2+, signed requests, per-org credentials
• Row Level Security isolates data per organization
• Consent gates all outward writes; revocations halt pushes
• Immutable audit trail for every sync and data access

Troubleshooting

• 401/403: Check scopes and client credentials/SMART tokens
• 404/timeout: Verify Base URL and network allowlists
• Mapping issues: confirm identifiers used for patient match