Medical Office Force — API Documentation
1. Overview
The Medical Office Force Standardized API is an HL7® FHIR® Release 4 API secured with the HL7 SMART App Launch Framework v2. Registered patient- and provider-facing applications authenticate and retrieve electronic health information consistent with USCDI and the US Core Implementation Guide. Population-level access is provided via FHIR Bulk Data.
2. Service Base URLs
- • FHIR base URL: https://mofapi.medicalofficeforce.co/fhir
- • Capability Statement: GET https://mofapi.medicalofficeforce.co/fhir/metadata
- • SMART discovery document: GET https://mofapi.medicalofficeforce.co/fhir/.well-known/smart-configuration
- • Service Base URL bundle: https://mofapi.medicalofficeforce.co/service-base-url-bundle
3. Standards and Versions
- • FHIR: HL7 FHIR Release 4, version 4.0.1
- • US Core Implementation Guide: STU 6.1.0
- • USCDI: Version 3 (October 2022 Errata)
- • SMART App Launch Framework: Release 2.0.0
- • FHIR Bulk Data Access (Flat FHIR): v1.0.0 (STU 1)
- • OpenID Connect: Core 1.0 (errata set 1)
4. API Syntax, Interactions, and Function Names
RESTful syntax: https://mofapi.medicalofficeforce.co/fhir/[ResourceType]?[parameter=value]&...
Supported interactions:
- - read: GET /fhir/[ResourceType]/[id]
- - search-type: GET /fhir/[ResourceType]?[search parameters]
- - capabilities: GET /fhir/metadata
- - Bulk $export: GET /fhir/$export | /fhir/Group/[id]/$export | /fhir/Patient/$export
Content negotiation: default application/fhir+json; use the Accept header for application/fhir+xml.
Common search parameters and their data types (the complete list per resource is in the Capability Statement):
- • Path: [id] (string; required for read).
- • Patient: identifier(token), name(string), family(string), given(string), birthdate(date), gender(token), address(string), email(token), phone(token), _id(token), _lastUpdated(date)
- • Condition: patient(reference), category(token), clinical-status(token), code(token), onset-date(date), recorded-date(date), _id(token)
- • Observation: patient(reference), category(token), code(token), date(date), value-quantity(quantity), status(token), _id(token)
- • MedicationRequest: patient(reference), intent(token), status(token), authoredon(date), code(token), _id(token)
Return variables / structures:
- - search-type returns a searchset Bundle (resourceType "Bundle") of matching resources.
- - read returns a single FHIR R4 resource instance.
- - $export returns 202 Accepted with a Content-Location polling URL, then a manifest of NDJSON files.
5. Authentication and Authorization (SMART App Launch v2.0.0)
OAuth 2.0 via SMART App Launch v2. Endpoints (also in the smart-configuration document, §2):
- • authorization_endpoint: https://mofapi.medicalofficeforce.co/fhir/auth/authorize
- • token_endpoint: https://mofapi.medicalofficeforce.co/fhir/auth/token
- • introspection_endpoint: https://mofapi.medicalofficeforce.co/fhir/auth/introspect
- • jwks_uri: https://mofapi.medicalofficeforce.co/fhir/auth/jwks
Supported: response_type=code; grant_type=authorization_code; PKCE (code_challenge_method S256); launch contexts launch-standalone and launch-ehr; OpenID Connect (sso-openid-connect).
Client types: public; confidential-symmetric (client_secret_basic / client_secret_post); confidential-asymmetric (private_key_jwt via jwks_uri).
Standalone-launch flow: the application calls /fhir/auth/authorize with response_type=code, client_id, redirect_uri, scope, state, aud=https://mofapi.medicalofficeforce.co/fhir, code_challenge, and code_challenge_method=S256; the user authenticates and authorizes; the server redirects back with an authorization code; the application POSTs to /fhir/auth/token with grant_type=authorization_code, code, redirect_uri, code_verifier, and client authentication; and receives an access_token, id_token, and (if offline_access was granted) a refresh_token.
6. Registration
Applications must be registered before production use. The API does not support dynamic client registration; to request registration, contact Medical Office Force at info@medicalofficeforce.com and provide: application name and description; application type (public or confidential); redirect URI(s); requested scopes; and a technical contact. Medical Office Force issues a client_id (and, for confidential-symmetric clients, a client_secret; confidential-asymmetric clients register a public JWKS reachable by the server).
7. Supported Scopes
openid, profile, fhirUser, launch, patient/*.read, user/*.read, offline_access. Both SMART v1 and SMART v2 (granular, resource-level) scopes are supported. patient/*.read and user/*.read grant read access to the authorized patient's or user's data; offline_access requests a refresh token.
8. Refresh Tokens (including native applications)
Refresh tokens are issued to applications granted the offline_access scope. Public and native applications obtain the initial refresh token through the PKCE-protected (S256) authorization_code flow — no client secret is required, and the code_verifier binds the token request to the original authorization request. The refresh token is returned in the token response alongside the access token.
9. US Core / USCDI Data
The API exposes USCDI v3 data via the US Core Implementation Guide STU 6.1.0 over FHIR R4 (4.0.1). Data is available through US Core resource types including: Patient, AllergyIntolerance, CarePlan, CareTeam, Condition, Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location, Medication, MedicationRequest, Observation (vital signs, laboratory, smoking status, and clinical results), Organization, Practitioner, PractitionerRole, Procedure, Provenance, RelatedPerson, ServiceRequest, and Specimen. The US Core Choices and References supported by the API are those defined by the US Core Implementation Guide STU 6.1.0. The machine-readable list of supported resources and search parameters is the Capability Statement at https://mofapi.medicalofficeforce.co/fhir/metadata.
10. Bulk Data / Population Services
Population-level access uses FHIR Bulk Data Access v1.0.0 via the $export operations in §4. The published list of service base URLs is at https://mofapi.medicalofficeforce.co/service-base-url-bundle.
11. Errors and Exception Handling
Errors return a standard HTTP status code with a FHIR OperationOutcome in the body:
- • 400 Bad Request — malformed request or invalid parameter
- • 401 Unauthorized — missing, invalid, or expired access token
- • 403 Forbidden — token lacks the required scope
- • 404 Not Found — resource or endpoint does not exist
- • 429 Too Many Requests — rate limit exceeded; retry with exponential backoff
- • 500 Internal Server Error — unexpected server error
Inspect OperationOutcome.issue (severity, code, diagnostics) for handling.
12. Mandatory Software Components and Configurations
A consuming application must support: TLS 1.2 or higher; OAuth 2.0 / SMART App Launch v2 with PKCE (S256); FHIR R4 JSON parsing (XML optional); and OpenID Connect for identity. Public and native applications must implement PKCE; confidential-asymmetric applications must publish a reachable JWKS. Required request configuration: Authorization: Bearer <access_token>; Accept: application/fhir+json; and aud set to the FHIR base URL during authorization.
13. Security — TLS
All API and authorization traffic is served exclusively over HTTPS and requires TLS 1.2 or higher. The server negotiates only TLS 1.2 and TLS 1.3; TLS 1.1, TLS 1.0, SSL 3.0, and SSL 2.0 are disabled and are not accepted. Connections use ECDHE key exchange with forward secrecy (TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 for TLS 1.2; TLS_AES_128_GCM_SHA256 for TLS 1.3).
14. Additional Data
Access for API Users is limited to the USCDI v3 / US Core data authorized by the granted SMART scopes; no data classes beyond US Core are exposed to API Users.
15. API Terms and Conditions
16. Support
info@medicalofficeforce.com · +1 (877) 581-8810