API Documentation for Client Application Developers

Updated August 30, 2017

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. 

Please complete the Registration Form in order to obtain a token.


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

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

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 http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.name
Sex Patient.gender http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.gender
Date of Birth Patient.birthDate http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.birthDate
Race Patient.extension http://hl7.org/fhir/2016Sep/extension-us-core-race.html
Ethnicity Patient.extension http://hl7.org/fhir/2016Sep/extension-us-core-ethnicity.html
Preferred Language Patient.communication http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.communication
Smoking Status Observation http://hl7.org/fhir/2016Sep/observation.html
Problems Condition http://hl7.org/fhir/2016Sep/condition.html
Medications MedicationStatement http://hl7.org/fhir/2016Sep/medicationstatement.html
Medication Allergies AllergyIntolerance http://hl7.org/fhir/2016Sep/allergyintolerance.html
Laboratory Tests Observation.code http://hl7.org/fhir/2016Sep/observation-definitions.html#Observation.code
Laboratory Values Results Observation.value[x] http://hl7.org/fhir/2016Sep/observation-definitions.html#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 http://hl7.org/fhir/2016Sep/immunization.html
Unique Device Identifiers Device.udiCarrier http://hl7.org/fhir/2016Sep/device-definitions.html#Device.udiCarrier
Assessment and Plan CarePlan http://hl7.org/fhir/2016Sep/careplan.html
Goals Goal http://hl7.org/fhir/2016Sep/goal.html
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:


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:


or (equivalently)


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:

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:


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:


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:

Resource Data Element Search Parameter
AllergyIntolerance.reaction.onset onset
CarePlan.period date
CareTeam.period date
Condition.onset onset
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 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.

Changes from previous editions:

10/20/2016 Initial version released.

Trademark Notice: HL7 and FHIR are registered trademarks of Health Level Seven International.

Copyright Notice: Copyright (c) 2016-2017 EMR Direct. All rights reserved.