Sphere EHR
API Documentation
Public technical documentation for the Sphere EHR standardized API for patient and population services under 45 CFR 170.315(g)(10).
Supported Standards
- FHIR
- HL7 FHIR R4 4.0.1
- USCDI
- USCDI v3
- US Core
- US Core 6.1.0
- SMART
- SMART App Launch 2.2.0
- Bulk Data
- HL7 FHIR Bulk Data Access 2.0.0
- Security
- TLS 1.2 or higher, OpenID Connect, OAuth 2.0, PKCE S256
Service Base URL
Production service base URLs are published at /services-base-url and /services-base-url.ndjson. Each listed Endpoint identifies the deployed FHIR R4 base URL used by SMART, FHIR read/search, and Bulk Data operations.
API Syntax and Function Names
| Function names | API syntax | Return variables and structures |
|---|---|---|
| SMART discovery | GET /.well-known/smart-configuration | JSON authorization metadata including issuer, endpoints, capabilities, and scopes_supported. |
| FHIR CapabilityStatement | GET /metadata and GET /fhir/r4/metadata | FHIR R4 CapabilityStatement with US Core 6.1.0 resource support. |
| FHIR read | GET /fhir/r4/{resourceType}/{id} | FHIR R4 resource or OperationOutcome. |
| FHIR search | GET /fhir/r4/{resourceType}?{searchParameters} | FHIR R4 searchset Bundle or OperationOutcome. |
| Patient compartment | GET /fhir/r4/Patient/{id}/$everything | FHIR R4 Bundle containing USCDI v3 data available to the authorized app. |
| Bulk Data export | GET /Patient/$export and GET /Group/{groupId}/$export | 202 Accepted with Content-Location for status polling, then NDJSON file URLs. |
| Service base URL list | GET /services-base-url and GET /services-base-url.ndjson | Organization and Endpoint resources identifying deployed FHIR service base URLs. |
Required and Optional Parameters
| Area | Required parameters and data types | Optional parameters and data types |
|---|---|---|
| OAuth authorization | response_type, client_id, redirect_uri, scope, state, aud | launch, code_challenge, code_challenge_method, prompt |
| OAuth token | grant_type, client_id, code or refresh_token as applicable | redirect_uri, code_verifier, client_assertion, client_assertion_type, scope |
| FHIR read | resourceType, id, Authorization bearer token | _format |
| FHIR search | resourceType, Authorization bearer token | _id, patient, category, code, date, _lastUpdated, _include, _revinclude, _sort, _count |
| Bulk Data | Authorization bearer token with system or patient export scope | _type, _since, _outputFormat, patient, includeAssociatedData |
Authorization Server
Applications register with the authorization server through the app registration workflow. Public native and browser applications use PKCE S256. Confidential applications and backend service clients use registered credentials or signed client assertions. The SMART discovery document publishes the authorization endpoint, token endpoint, JWKS URL, supported capabilities, supported scopes, and token revocation endpoint.
Refresh token support is available for offline_access. Native applications capable of securing a refresh token receive refresh tokens valid for at least three months, subject to revocation and rotation. Access tokens expire after 3600 seconds. Token revocation takes effect immediately; revoking an access token also revokes bound refresh tokens for the same client and subject.
USCDI to FHIR Traceability
The API exposes USCDI v3 data using US Core 6.1.0 profiles and FHIR R4 resources. Resource-specific SMART scopes use patient/{Resource}.rs, patient/{Resource}.read, and applicable system/{Resource}.rs or system/{Resource}.read forms.
Exceptions and Exception Handling Methods
| Return | Exception handling method |
|---|---|
400 invalid_request | Malformed OAuth, FHIR, or Bulk Data request. |
401 invalid_token | Missing, expired, revoked, or invalid bearer token. |
403 insufficient_scope | Token does not authorize the requested resource, patient, or operation. |
404 not_found | Resource, patient, group, export job, or file was not found. |
429 too_many_requests | Client exceeded the configured rate limit. |
500 server_error | Unexpected server condition; response omits PHI and secret values. |
Mandatory Software Components
- FHIR R4 resource server with US Core 6.1.0 support.
- SMART App Launch 2.2.0 authorization server.
- Bulk Data Access 2.0.0 export worker and durable NDJSON storage.
- Public JWKS endpoint for token verification.
- Public service base URL publication endpoint.
Mandatory Software Configurations
- TLS 1.2 or higher is required for every production API endpoint.
- Authorization scopes must be registered before an application requests access.
- Redirect URIs must exactly match registered application values.
- Bulk Data exports require configured durable storage before certification use.
- Rate limits are enforced per registered application or backend client.
Terms and Conditions
Third-party app developers may register and test the standardized API at no additional fee. Customer subscription, implementation, Direct messaging, and e-prescribing cost disclosures are published on the Certification disclosure page. API use remains subject to the customer agreement, Business Associate Agreement when PHI is exchanged, privacy controls, and security controls.