PracticeHI FHIR API

Standards-based patient and practice data access for applications, patients and health information networks. FHIR R4 · US Core 7.0.0 (USCDI v4) · SMART App Launch 2.2 · Bulk Data Access 2.0. This page is public and needs no account.

Service base URL

One base URL serves every practice on PracticeHI; the practice a request reaches is the one the access token was issued for.

https://practicehi.com/fhir/r4

Standards and versions

Registering an application

Applications are registered by PracticeHI for the practice(s) that will authorize them; there is no self-service registration form. Registration is open to any developer. Send the request through PracticeHI Support (the Support conversation inside the application, available to any practice user) or to the contact published at practicehi.com, with:

• the application's name and a short description, and the developer's contact;
• the client type: public (native or browser app; PKCE, no secret), confidential — symmetric (a client secret) or confidential — asymmetric (a JWKS URL; assertions signed RS384 or ES384);
• the redirect URI(s), exactly as the app will present them (https only);
• for an EHR launch, the launch URL;
• for backend services (bulk data), the JWKS URL and the practice the client will export;
• whether the app is patient-facing (patient scopes) or clinician-facing (user scopes), or both.

You receive a client id (and a secret when symmetric). A single registration serves single-patient (SMART) and multi-patient (bulk) access as requested; the same process registers a client for one practice or many.

Scopes

Every resource type below may be named with patient/ (the authorizing patient's record) or user/ (what the signed-in user may see) and the permissions .r, .s, .rs (or v1 .read); patient/*.rs and user/*.rs name them all. Backend-services clients receive system/*.read.

AllergyIntolerance CarePlan CareTeam Condition Coverage Device DiagnosticReport DocumentReference Encounter Endpoint EpisodeOfCare Goal Immunization Location MedicationDispense MedicationRequest MedicationStatement Observation Organization Patient Practitioner PractitionerRole Procedure Provenance QuestionnaireResponse RelatedPerson ServiceRequest Specimen

Named but served without data (the practice records none; a search answers an empty set): Medication.

The person authorizing chooses which parts of the record an app may see (all, none, or by type and category); the app is granted what was allowed and the token response's scope says what that was.

Tokens and sessions

Reading data

• GET {base}/Patient/{id}, GET {base}/{Type}?patient={id}&…, POST {base}/{Type}/_search; paging with _count (max 200) and _offset; _revinclude=Provenance:target on Patient and every clinical search; GET {base}/Patient/{id}/$everything.
• A search parameter the server does not support is refused with an OperationOutcome rather than ignored; a clinical search without patient is refused; every read is audited under HIPAA.
• Clinical notes: DocumentReference (with Binary/{id} for the content) and DiagnosticReport; laboratory results as Observation (category laboratory) and DiagnosticReport (category LAB); vital signs, social history (smoking status, pregnancy status and intent, occupation), screening and assessment instruments as Observation.
• Errors: OperationOutcome with the HTTP status (400 malformed, 401 no or expired token, 403 outside the grant, 404 not found or outside the practice).

Bulk data (multi-patient)

GET https://practicehi.com/fhir/r4/Group/practice-{practiceId}/$export
Accept: application/fhir+json
Prefer: respond-async
Authorization: Bearer {system token}

Answers 202 Accepted with Content-Location = the status URL; poll it (202 while running, 200 with the manifest when complete); fetch each file with the same token; DELETE the status URL to cancel. _type narrows the types, _since keeps resources whose meta.lastUpdated (or principal date) is not before the instant; resources referenced by the exported ones (practitioners, organizations, locations) are included regardless of their date. Files stay until the export is cancelled or superseded; fetch them promptly.

Terms of use

• No fees are charged to developers, or to patient-facing applications, to register with or use this API.
• Access to a person's data requires that person's (or an authorized user's) authorization through the SMART flow above; an application receives no more than the scopes it was granted. Applications must handle protected health information lawfully and may not use it for purposes the person did not authorize.
• PracticeHI may suspend a client that threatens the availability or security of the service; the developer is notified and the suspension lifted when the concern is resolved.
• Changes to this API are announced on this page with at least 30 days' notice for a breaking change; the capability statement is the authoritative description of what is served today.