170.315(g)(10) Standardized API for Patient and Population Services #

This document describes the Data Holder-side API integration required to publish a standardized, read-only RESTful FHIR R4 public API through EMR Direct Interoperability Engine 2026. The Interoperability Engine exposes public-facing OAuth 2.0 and FHIR endpoints and translates those requests into phiQuery connector method calls routed over a TLS connection to the Data Holder’s phiQuery listener.

LegendEHR utilizes integration with EMRDirect to fulfill this requirement. Core technical documentation and additional resources are available at https://appstudio.interopengine.com.

 

Section 1: API Syntax #

API Name: LegendEHR FHIR R4 Standardized API

Intended Purpose: The LegendEHR FHIR R4 Standardized API is designed to provide secure, standards-based access to patient and population-level health data maintained by the Health IT Module. The API enables authorized third-party applications to retrieve read-only FHIR R4 resources in accordance with 45 CFR 170.315(g)(10), using OAuth 2.0 for authentication and authorization. The API supports both patient-mediated and system-to-system access.

API Syntax

FHIR R4 Base URL:

Feature	Specification
Architecture	RESTful API based on the HL7 FHIR Standard R4 release.
Protocol	HTTPS exclusively.
Data Format	JSON. All requests and responses use the FHIR JSON media type (application/fhir+json).
Base URL	https://sandbox-r4.interopengine.com/fhir/r4/legendehr

 

OAuth Endpoints:

Endpoint	URL
Authorization	https://sandbox-r4.interopengine.com/oauth/legendehr/authz
Registration	https://sandbox-r4.interopengine.com/oauth/legendehr/registration
Token	https://sandbox-r4.interopengine.com/oauth/legendehr/token

 

Section 2: Function names, parameters, returns, and exceptions #

Authenticate public API user #

Function name: authenticateAPIUser / AuthenticateAPIUser

Purpose: Validate user credentials (and authorize the user to use the specified client application for API access).

Parameters:

• sessionInfo (SessionInfo): public API session information
• authInfo (AuthInfo): authentication and authorization information (credentials, grant type, client attributes)

Return:

• Boolean true if authenticated and authorized; false if not authenticated; or throw PhiQueryException for error conditions.

 

Language	Signature
Node.js	authenticateAPIUser(sessionInfo, authInfo) → {boolean}

#

Patient identifier and patient search #

Patient identifiers are returned via getDataCategory for the Patients category using search criteria. The patient identifier is returned as the result ID using the ‘id’ simple extension. Patient identifiers must be permanent, unique per datasource, and must never change once assigned.

Query for data category by search criteria #

Function name: getDataCategory

Parameters:

• sessionInfo (SessionInfo)
• patientID (String, nullable): permanent patient logical identifier, or null to search across authorized patients / non-patient categories
• category (DataCategory enum or language equivalent): requested category
• searchInfo (List<SearchFilter>): search criteria filters (may be empty)

Return:

• List of CategoryResult objects; empty list if no match; or throw PhiQueryException for error conditions.

 

Language	Signature
Node.js	getDataCategory(sessionInfo, patientID, category, searchInfo) → {Array.<CategoryResult>}

Query for data category by result ID #

Function name: getDataCategoryByResultID

Parameters:

• sessionInfo (SessionInfo)
• category (DataCategory)
• resultID (String): permanent logical identifier for the result

Return:

• Exactly one CategoryResult if found and authorized; null/empty result if not found; or throw PhiQueryException for error conditions.

 

Language	Signature
Node.js	getDataCategoryByResultID(sessionInfo, patientID, category, resultID, searchInfo) → (nullable) {CategoryResult}

Return variables, structures, and supported data categories #

CategoryResult is the return structure for category queries. Constructors include:

• CategoryResult(CodeSystem system, String code, String display)
• CategoryResult() (convenience for non-coded categories; equivalent to PQ_TYPE/uncoded)
• CategoryResult supports convenience methods including:
• setDate(date) or setDates(startDate, endDate) using YYYY-MM-DD format
• setValue(value, units) for simple values with optional units (complex values should use elements)
• setSimpleExtension(name, value) and addComplexExtension(name, CategoryResult value)

Required DataCategory values for g(10) #

The Data Holder must be capable of returning all categories required for g(10) certification, including (non-exhaustive list shown below):

FHIR Resource	Coded?	DataCategory enum value
AllergyIntolerance	Yes	ALLERGIES_AND_INTOLERANCES
CarePlan	Text	CARE_PLANS
CareTeam	No	CARE_TEAMS
Condition	Yes	CONDITIONS
Coverage	No	COVERAGE
Device	Yes	DEVICES
DiagnosticReport	No	DIAGNOSTIC_REPORTS
DocumentReference	No	DOCUMENT_REFERENCES
Encounter	No	ENCOUNTERS
Goal	Text	GOALS
Immunization	Yes	IMMUNIZATIONS
MedicationDispense	Yes	MEDICATION_DISPENSE
MedicationRequest	Yes	MEDICATION_REQUESTS
Observation	Yes	OBSERVATIONS
Patient	No	PATIENTS
Procedure	Yes	PROCEDURES
RelatedPerson	No	RELATED_PERSONS
ServiceRequest	Yes	SERVICE_REQUESTS
Specimen	No	SPECIMENS
Binary	No	RAW_DATA
Endpoint	No	ENDPOINTS
Group	No	GROUPS
Location	No	LOCATIONS
Organization	No	ORGANIZATIONS
Media	No	MEDIA
Person	No	PERSONS
Practitioner	No	PRACTITIONERS
PractitionerRole	No	PRACTITIONER_ROLES
Provenance	No	PROVENANCE

Code systems #

CodeSystem enum values recognized by the connector include (examples):

• LOINC (DiagnosticReport, Observation), SNOMED_CT (Condition/Procedure/Observation), RXNORM (MedicationRequest, AllergyIntolerance)
• CVX (Immunization), FDA_UDI (Device), NUCC (PractitionerRole), RFC_5646 (Patient preferred language)
• PQ_TYPE for non-coded categories (including ‘uncoded’ and ‘text’ codes)

 

Exceptions and error handling #

Connector methods may throw PhiQueryException to signal error conditions back to the Interoperability Engine server. Mapped local errors to appropriate phiQuery exception conditions (e.g., not authorized, invalid request, resource unavailable) and ensure audit logging captures the requestId/sessionToken and relevant failure context.

Note: This document summarizes exception usage as described in the EMR Direct phiQuery Data Holder guide; consult the vendor guide for the complete exception taxonomy.

 

Mandatory Software Components and Configurations #

To successfully interact with the LegendEHR FHIR R4 Standardized API and process its responses, an application must implement secure transport, OAuth 2.0 authorization, and FHIR R4 request/response handling consistent with the API’s published specifications. Applications must be capable of establishing TLS 1.2 or higher connections, obtaining and presenting OAuth 2.0 access tokens as Bearer tokens, issuing RESTful FHIR R4 requests, and processing FHIR R4 JSON responses. The API is read-only and requires adherence to applicable authorization scopes, patient context restrictions, and rate limiting policies.

 

 

Technical Requirements and Attributes Necessary for API Interaction #

To successfully interact with the LegendEHR FHIR R4 Standardized API and process its responses, an application must implement the technical capabilities described below. These requirements ensure secure authentication, authorized access, standards-based interoperability, and proper handling of responses.

Applications must be capable of establishing secure HTTPS connections using TLS 1.2 or higher, implementing OAuth 2.0 authorization workflows, issuing RESTful FHIR R4 requests, and processing FHIR R4-compliant JSON responses. The API supports read-only access to clinical and administrative data and enforces authorization, scope validation, and patient context restrictions consistent with FHIR R4 Standardized API.

1. Transport and Network Requirements

Applications must:

• Support HTTPS connections using TLS 1.2 or higher
• Validate server certificates
• Use DNS-resolvable public endpoint URLs
• Send and receive UTF-8 encoded JSON payloads

 

2. OAuth 2.0 Authorization Requirements

Applications must support OAuth 2.0 and:

• Register as a client (static or dynamic registration as supported)
• Request access tokens from the token endpoint
• Include access tokens as:

Authorization: Bearer {access_token}

• Support applicable grant types:
  • authorization_code
  • client_credentials

• Handle:
  • Token expiration
  • Token refresh (if applicable)
  • Invalid or insufficient scope responses

 

3. FHIR R4 Request Requirements

Applications must:

• Construct RESTful FHIR R4 requests using HTTP GET
• Use the base FHIR endpoint provided by the Health IT Module
• Support standard FHIR resource-level search parameters
• Handle:
  • Single resource retrieval
  • Search queries
  • Bundle responses
  • Pagination via link elements