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 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:”.

Download Open API Documentation for Client Application Developers – Open API Documentation PDF

This API document is for the interface from Eprosystem Inc., EHR : EproMedical version 3.0.0 to EMR Direct, Interoperability Engine.

1. Introduction

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 SSL/TLS connections (TLS 1.0 or higher) are accepted. All plaintext connections will be refused.

Note: Please limit your connect ion 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 map 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. Th e 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:

ENDPOINT	URL
Authorization	https://[baseOAuthURL]/authz
Token	https://[baseOAuthURL]/token
Registration	https://[baseOAuthURL]/register

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 use r 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):

COMMON CLINICAL DATA SET ELEMENT	RESOURCE	RESOURCE DATA ELEMENT (IF APPLICABLE)
Patient Name	Patient	Patient.name
Sex	Patient	Patient.gender
Date of Birth	Patient	Patient.birthDate
Race	Patient	Patient.extension
Ethnicity	Patient	Patient.extension
Preferred Language	Patient	Patient.communication
Smoking Status	Observation
Problems	Condition
Medications	MedicationStatement
Medication Allergies	AllergyIntolerance
Laboratory Tests	Observation	Observation.code
Laboratory Values Results	Observation	Observation.value[x]
Vital Signs	Observation
Procedures	Procedure
Care Team Members	CareTeam
Immunizations	Immunization
Unique Device Identifiers	Device	Device.udiCarrier
Assessment and Plan	CarePlan
Goals	Goal
Health Concerns	Condition

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:

COMMON CLINICAL DATA SET ELEMENT	RESOURCE OR DATA ELEMENT	URL FOR ADDITIONAL INFORMATION
Patient Name	Patient.name
Sex	Patient.gender
Date of Birth	Patient.birthDate
Race	Patient.extension
Ethnicity	Patient.extension
Preferred Language	Patient.communication
Smoking Status	Observation
Problems	Condition
Medications	MedicationStatement
Medication Allergies	AllergyIntolerance
Laboratory Values Results	Observation.value[x]
Vital Signs	Observation	http://hl7.org/fhir/2016Sep/observation.html
Procedures	Procedure	http://hl7.org/fhir/2016Sep/procedure.html
Care Team Members	CareTeam	http://hl7.org/fhir/2016Sep/careteam.html
Immunizations	Immunization
Unique Device Identifiers	Device.udiCarrier
Assessment and Plan	CarePlan
Goals	Goal
Health Concerns	Condition	http://hl7.org/fhir/2016Sep/condition.html

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:

RESOURCE DATA ELEMENT	SEARCH PARAMETER
Patient.name.family	family
Patient.birthDate	birthdate

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 h as 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 represent ed by a single Resource type:

CCDS ELEMENT	SEARCH TERM
Health Concern	category=http://argonaut.hl7.org/extension-codes\|health-concern
Problem	category=http://argonaut.hl7.org/extension-codes\|problem
Smoking Status	code=http://loinc.org\|72166-2
Vital Signs	category=http://hl7.org/fhir/observation-category\|vital-signs
Laboratory Tests & Laboratory Values/Results	category=http://hl7.org/fhir/observation-category\|laboratory

For example, to retrieve the Smoking Status for Patient 1234, the request could be formatted as: https://[baseURL]/Patient/1234/Observation?code=http://loinc.or g|72166-2

The API return types (XML or JSON) for the data categories are specified in the reference linked in our documentation. For the FHIR queries, Section 2(a) of our documentation refers the developer to the RESTful API FHIR syntax found at http://hl7.org/fhir/2016Sep/http.html which states that

“The formal MIME – type for FHIR resources is appl ication/fhir+xml or application/fhir+json”

Our HealthToGo client application requests the JSON format.

An example of the API return for the data category demographic can be viewed in the original downloadable PDF below.

Download Open API Documentation for Client Application Developers – Open API Documentation PDF

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.

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.

RESOURCE DATA ELEMENT	SEARCH PARAMETER
AllergyIntolerance.reaction.onset	onset
CarePlan.period	date
CareTeam.period	date
Condition.onset	onset-date
Goal.target	targetdate
Immunization.date	date
MedicationStatement.effective	effective
Observation.effective	date
Procedure.performed	date
DocuementReference.period	period

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 implementer 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.

Terms of Use: http://www.interopengine.com/open-api-terms

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: Copyright (c) 20 18 EMR Direct. All rights reserved

Website Terms of Use: https://www.emrdirect.com/terms.html