1. Introduction

This guide is written for third party developers, including patients, who are developing software applications for accessing Protected Health Information (PHI) based on this documentation of an open API. This documentation allows applications to query a public-facing API enabled by a Data Holder. Data Holders wishing to publish such a public-facing API should have their Health IT vendor register as a developer integrator of EMR Direct Interoperability Engine services at https://www.emrdirect.com/subscribe-developer.

ALWAYS KEEP IN MIND THAT ONLINE DATA TRANSFER IS NOT A SUBSTITUTE FOR PERSON-TO-PERSON COMMUNICATION OF URGENT OR CRITICAL MEDICAL INFORMATION.

This documentation also contains general information and important security information. General information will be marked as:

Note:

and important security information will be marked as:

Important:

2. General Concepts

a. Application Access Requests

The API is a read-only RESTful FHIR® STU 3 Ballot API and follows the syntax described at http://hl7.org/fhir/2016Sep/http.html.

All data access requests will be in the following format, in which the [base] URL will need to be obtained from the Data Holder, either directly or via directory information: GET [base]/[resource-specific parameters]…

b. Connecting to the server

The server is accessed by clients through an https connection.

Important: Local customer security policies must be in place to prevent unauthorized monitoring or eavesdropping of connections to the server.

Note: Only TLS 1.2 connections are accepted. All plaintext connections will be refused.

Note: Please limit your connection frequency to a value appropriate for your use case. Connection attempts which are more frequent than permitted by the bandwidth allocation for the data resource are not allowed.

c. Authentication – Obtaining an Access Token

Client authentication can be performed using a username and strong password. A healthcare organization may reuse existing patient portal credentials for this purpose, in which case the authenticated username maps to a unique patient portal user on the resource holder’s side. The end user should obtain these credentials directly from the healthcare organizations from which they wish to access data.

Prior to making API requests, the client application must obtain an Access Token from the associated Authorization Server. The client software must support the OAuth 2.0 authorization code grant flow as detailed in RFC 6749. If the client application does not have a client ID and client secret for this purpose, the client application may obtain a client ID and client secret using the dynamic client registration protocol by submitting the required client information to the registration endpoint as detailed in RFC 7591.

Each healthcare organization will have a unique base URL to access its Authorization Server. The required endpoint URLs are as follows:

When the end user is directed to the authorization endpoint, the user will be presented with a login screen where they can enter their credentials for the healthcare organization they are accessing. If the correct credentials are supplied and the end user grants access to the client application, an authorization code will be returned to the client that the client application can use to obtain an access token through the token endpoint.

All requests to the API must include the access token transmitted in the Authorization header of the HTTP request as a bearer token as illustrated in RFC 6749. If the access token is missing, expired, or otherwise not valid for the requested operation, the API will return a 401 Unauthorized response.

3. API Details

a. Query a Specific Data Category Resource

Client software must be capable of making HTTPS RESTful requests in accordance with the FHIR specification and consuming the following FHIR Resources in order to support the Common Clinical Data Set (CCDS):

General specifications for FHIR resources and the associated data elements can be found at http://www.hl7.org/fhir/2016Sep/resourcelist.html.

Additional information for the FHIR Resource or Data Element used to represent each data category can be found at the URLs listed in the following table:

Note: Authentication certificates or passwords can be reset by the Data Holder.

b. Patient Selection

To search for patients, the application should request a bundle of Patient resources matching suitable search criteria. To facilitate this, the following optional search parameters can be applied to the Patient resource:

For example, to retrieve a bundle of Patient resources to which the user is authorized, where the patient’s last name is Smith and the patient was born on July 4, 1976, the request could be formatted as:

https://[baseURL]/Patient?family=Smith&birthdate=1976-07-04

The API will return a bundle of all patients (possibly zero) matching the search criteria. Only patients for which the user has been authorized access will be included in the results. Each patient returned in the search results is assigned a unique patient ID that can be found in the Patient.id element of the corresponding Patient resource. This patient ID can be included in subsequent requests to retrieve additional resources for that specific patient.

c. Query for a Specific Data Category

The Patient resource can be retrieved by specifying a specific patient ID or by performing a search as discussed in section 5(b). The remaining resource types listed in Section 5(a) can be accessed for a specific patient as a Bundle of resources by performing a search by resource type or by patient compartment and specifying the patient ID in the request. For example, to retrieve a bundle of Immunization resources containing all available immunization history for Patient 1234, the request could be formatted as:

https://[baseURL]/Immunization?patient=1234

or (equivalently)

https://[baseURL]/Patient/1234/Immunization

The following search terms can be used to isolate results for a single CCDS category in cases where two or more CCDS categories are represented by a single Resource type:

For example, to retrieve the Smoking Status for Patient 1234, the request could be formatted as:

https://[baseURL]/Patient/1234/Observation?code=http://loinc.org|72166-2

Each search request will return a bundle of zero or more results meeting the search criteria.

d. Query for All Data as a CCDA document

CCDA documents can be accessed within DocumentReference resources. CCDAs are categorized as “Summary of Episode” Notes with LOINC code 34133-9. For example, to request a CCDA document covering all dates for patient 1234, the query could be formatted as:

https://[baseURL]/DocumentReference?patient=1234&type=http://loinc.org|34133-9

The Base64 encoded CCDA XML data can be found in the DocumentReference.content.attchment.data element of the returned DocumentReference resource

e. Query for a Specific Date or Date Range

The CCDS data categories or CCDA documents returned by the API may be limited by date by specifying either (1) a specific date or (2) start and/or end dates. These dates can be included as FHIR STU3 search parameters as defined at http://hl7.org/fhir/2016Sep/http.html#search. Specifying a date or date range in the request is optional. The following table lists the supported search parameters for this purpose:

f. Error Handling

If the access token used in the request is invalid, expired, or the user has not been authorized to access the requested Resource, the API will return a 401 Unauthorized HTTP response.

If the request cannot be processed for other reasons (temporarily unavailable, unsupported resource type, system error, etc.), the API will return a 400 Bad Request HTTP response containing an OperationOutcome Resource with additional information regarding the issue contained in the OperationOutcome.issue element.

Handling of OAuth-related errors is detailed in RFC 6749.

Handling of dynamic client registration errors is detailed in RFC 7591.

4. Frequently Asked Questions

a. How do I access production API resources with my client application?

Please obtain [base] URL resource information from a specific healthcare provider organization when you are ready to begin allowing client end users to access PHI with production credentials. Each clinical data source accessible through the API will have a unique Base URL.

b. How extensible is the Interoperability Engine API?

API resources are modeled after the HL7 FHIR Standard for Trial Use 3 (STU 3) Ballot which is in ballot stage as of this writing. This internationally-recognized API standard has been extended to include the additional data categories needed for use in systems certifying to the 2015 Edition Certification Criteria’s Common Clinical Data Set requirements. The API is designed to optimally interface with client applications while being comprehensive as a 2015 Edition solution for implementers wishing to rely on EMR Direct Interoperability Engine for Application Access services. This guide will help you access the data categories enabled by 2015 Edition Application Access APIs.

c. How do end users and applications authenticate to the API?

The API is designed to support existing patient portal credentials via the OAuth 2.0 authorization framework as per RFC 6749. The OAuth server also supports dynamic client registration as per RFC 7591.

d. What data is available through the API?

The API will return all properly formatted data provided by a connected data source system in response to a submitted query. Healthcare organizations may have their own policies and/or safety best practices that will dictate what data can be sent and when data is considered complete and/or ready to be sent. Please contact a healthcare organization directly for questions related to their specific policies.

e. What additional options are offered?

Interoperability Engine 2017 also supports FHIR DSTU2 (with the Argonaut Data Query IG profiles), the SMART App Launch Framework (both standalone launch and EHR launch), SMART clinical scopes (patient, user, and system scopes), Open ID Connect, UMA (with the HEART profile), OAuth 2.0 client credentials flow, OAuth 2.0 refresh tokens, OAuth 2.0 revocation, the Unified Data Access Profiles, manual client registration, sandbox access for testing, and more. Please contact the Data Holder to determine which additional options have been enabled by the Data Holder for a particular endpoint.

Trademark Notice: Interoperability Engine and the Interoperability Engine gears logo are trademarks of EMR Direct. HL7 and FHIR are registered trademarks of Health Level Seven International.

Copyright Notice: © 2024 EMR Direct. All rights reserved.