ONC-certified FHIR API

ReasonEMR for developers

Connect patient, clinician, and population-health applications to ReasonEMR with HL7® FHIR® R4 and SMART on FHIR.

Overview

  • HL7 FHIR R4 (4.0.1), JSON (application/fhir+json)
  • US Core 6.1.0 / USCDI v3
  • SMART App Launch 2.0 (v1 and v2 scopes, granular scopes, PKCE, OpenID Connect)
  • Bulk Data Access 1.0 (Backend Services, Group/$export, _since)
  • TLS 1.2 or higher is required on every endpoint.

Finding a clinic's FHIR endpoint

Each ReasonEMR clinic has its own FHIR service base URL of the form https://<clinic>.reasonemr.com/api/fhir.

The complete, machine-readable list of every customer's service base URL is published free of charge as a FHIR Bundle of Organization and Endpoint resources:

https://reasonemr.com/api/public/fhir-endpoints

Authorization (SMART on FHIR)

Discover the authorization server from each clinic's base URL. In the table, {base} is the FHIR base URL and {origin} is the clinic host.

DiscoveryGET {base}/.well-known/smart-configuration
Capability statementGET {base}/metadata
AuthorizeGET or POST {origin}/api/smart/authorize
TokenPOST {origin}/api/smart/token
Dynamic registration (RFC 7591)POST {origin}/api/smart/register
Token introspection (RFC 7662)POST {origin}/api/smart/introspect
Token revocation (RFC 7009)POST {origin}/api/smart/revoke
OpenID Connect JWKSGET {origin}/api/smart/jwks
Bulk export (group)GET {base}/Group/{id}/$export

Supported launch types

  • Patient standalone launch — the patient signs in with their patient-portal account and chooses which data to share.
  • EHR launch — launched by a clinician from inside ReasonEMR with patient (and encounter) context.
  • Clinician standalone launch — staff sign in and pick a patient.
  • Backend Services — system-to-system access for bulk export using private_key_jwt and system/* scopes.

Client types & registration

  • Public clients (native and browser apps) must use PKCE (S256).
  • Confidential clients may authenticate with a client secret or an asymmetric private_key_jwt assertion (RS384, ES384, RS256, ES256) using an inline jwks or jwks_uri.
  • Register with OAuth 2.0 Dynamic Client Registration (POST /api/smart/register) or ask the clinic's administrator to register your app in Settings → API / Apps.

Scopes

  • patient/*, user/* and system/* resource scopes in SMART v1 (.read) and v2 (.rs, .cruds) syntax.
  • Granular v2 scopes, e.g. patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory. When an app requests a resource-level Condition or Observation scope, the patient can choose to grant only specific categories.
  • launch, launch/patient, openid, fhirUser, offline_access.

Tokens

  • Access tokens are valid for 1 hour.
  • Refresh tokens (with offline_access) are valid for at least three months, and each refresh issues a new refresh token valid for a new period without re-authorization.
  • Patients can revoke an app at any time in the patient portal (Settings → Connected apps); revocation takes effect immediately.

Resources & search

All USCDI v3 data is available through the following US Core resources. Read (GET [base]/[type]/[id]) and search (GET [base]/[type]?… or POST …/_search) are supported. The authoritative list of search parameters, operations, and profiles for each resource is the server's CapabilityStatement at GET [base]/metadata.

AllergyIntoleranceCarePlanCareTeamConditionCoverageDeviceDiagnosticReportDocumentReferenceEncounterGoalImmunizationLocationMedicationDispenseMedicationRequestObservationOrganizationPatientPractitionerPractitionerRoleProcedureProvenanceQuestionnaireResponseRelatedPersonServiceRequestSpecimen

Responses are FHIR resources or searchset Bundles. Errors return an OperationOutcome with the matching HTTP status (400 invalid request, 401 missing/expired token, 403 insufficient scope, 404 not found).

Terms of use, fees & support

Terms of use
Use of the API is governed by the ReasonEMR FHIR API Terms of Use.
Fees
Free. ReasonEMR charges no fees — to patients, app developers, or clinics — for access to the FHIR API, including documentation, app registration, service base URLs, and production use.
Developer support
baljinder@reasonworks.ai

See also our security and privacy practices.