Documentation

Terms of Use

Documentation of API portal and materials including support of the FHIR® Specification (referred to as the “Materials”) have been made available to developers for development and testing. The Materials are provided to developers as-is with no other warranties expressed or implied. Developers may use the Materials with adherence to the below terms and conditions:

1. StreamlineMD FHIRAPI portal has the most up-to-date documentation. Developers may keep copies of the Materials; however, they may not be distributed.
2. Developers own developments using the Materials. StreamlineMD owns the Materials, as well as any improvements to or derivatives of the Materials, such as enhancements to the testing tools or documentation. A dynamic developer environment is encouraged. Any suggested improvements of the Materials may become part of the Materials without any obligation or notice to the submitter.
3. Developers are responsible for the products developed and how the products connect to the community members’ software. Developers are also responsible for complying with all applicable laws, including not infringing on StreamlineMD’s or others’ intellectual property rights.
4. Developers interested in advertising products using StreamlineMD EHR FHIRAPI, StreamlineMD's name, or StreamlineMD's logo, please contact helpdesk@streamlinemd.com to obtain permission.

Introduction

Integration with the SMART App Launch Framework via FHIR allows a third-party application to connect with Provider(s) using the StreamlineMD EHR and retrieve Electronic Health Record data from those Providers. These applications can be launched from inside or outside the user interface of StreamlineMD EHR. The framework supports Apps that can be used by clinicians, patients, and others via a PHR or Patient Portal or any FHIR system where a user can give permissions to launch an App. StreamlineMD EHR has built this API using the HL7 FHIR standards.

This documentation is intended for use by third-party application developers which will describe registration, syntax, functionality and errors/exceptions they will see when using the StreamlineMD FHIR API to integrate with provider(s)/ practices using the StreamlineMD EHR.

FHIR R4 Base URLs

Download List of FHIR R4 Base URLs

Click here to download a machine-readable CSV file of all StreamlineMD and non-StreamlineMD FHIR R4 base URLs certified to the ONC’s Cures Act Final Rule (g)(10) criterion, along with the patient-facing names of associated healthcare organizations.

SVAP (Standards Version Advancement Process)

Content: StreamlineMD EHR uses SVAP for ONC g(10) FHIR API. StreamlineMD EHR uses SVAP US CORE V 4.0.0.

Registration

Developers wishing to integrate with the StreamlineMD FHIR API must complete the registration process. Once the request is approved the developer will be able to consume the StreamlineMD FHIR API. Depending on the access type the Client ID and/ or Client Secret shall be provided.

During setup, developers will be required to provide the Practice Administrator with the following information about their App needs:

1. “Confidential App” vs. “Public App”
   • The Practice Administrator will set the developer application as a “Confidential App” if the app is able to protect a client_secret.
   • The Practice Administrator will set the developer application as a “Public App” if the app is unable to protect a client_secret.
2. Developers will be required to provide the Practice Administrator with a “redirect_uri”. This is a security measure used to make sure that the API only sends responses back to the verified redirect URI of the developer.

Finally, developers can request/provide the following information to the Practice Administrator during App setup:

1. EHR Launch Access: Developers can request “Launch” access by providing a Launch URI to the Practice Administrator during registration. See the “Launch Sequence” section for more information about the EHR Launch sequence.
2. Bulk Export Access: Developers can request “Export” access by providing JWK Set URL with at least one valid JWK in the RS384 format. See the “Bulk Export” section for more information about Bulk Exporting.

Configurations

A third-party developer App needs to meet the following configuration requirements:

1. The App must read and parse JSON responses.
2. The App must assure that sensitive information (authentication secrets, authorization codes, tokens) are transmitted ONLY to authenticated servers, over TLS-secured channels. §170.315(g)(10) requires secure connection using TLS version 1.2 or higher.
3. If the App is a Bulk Export application, the application may need to be setup to handle longer lasting connections based on the data that are being exported.
4. The App must send requests over HTTPS.

Launch Sequence

Depending on how your developer account has been setup will change how you communicate with the API to obtain authorization tokens and subsequently access to the StreamlineMD FHIR Resources.

Before the developer can obtain an authorization token, they will need some context of where to retrieve the tokens (such as token endpoints, authorization endpoints, etc.)

Below are the ways in which your Application can handle initial “kickoff” requests BEFORE authorization tokens are granted:

EHR Launch

In an EHR Launch, a user establishes an EHR session and then decides to launch your App from within the EHR (such as a dashboard, single-patient app, scheduler, appointment manager, etc.) The EHR will initiate the “Launch Sequence” by opening a new browser instance (or perhaps an iframe) and point to your App’s registered Launch URI with some additional context.

Below are the “context” parameters included in a Launch request to your application:

Launch Parameters

An example “Launch Request” that your App can expect to see may look something like this:

On receiving the launch notification, your App would call the issuer’s (iss) “.well-known/smart-configuration” endpoint which contains the OAuth authorization and token endpoint URLs to use when requesting authorization to access FHIR resources.

An example “Call” that your App would make after getting the “iss” (where “FHIR_ENDPOINT” is the “iss” from the launch sequence):

Later, when your App prepares a list of access scopes you want to request from the EHR authorization server, it will be associated with the existing EHR context by including the launch notification in the scope.

Standalone Launch

In the Standalone Launch, a user selects your App from outside the EHR (such as tapping an App icon on mobile devices, or maybe even from another application). Your App will launch from its own URL without Launch Context (such as in the EHR Launch sequence).

Once your App has been launched, in order to obtain further context and request authorization to access FHIR resources, your App will need to discover the EHR’s OAuth authorize and token endpoint URLs by querying the “.well-known/smart-configuration” endpoint.

An example “Call” that your App would make:

Finally, your App can declare its own launch context requirements by adding specific scopes to the request it sends to the EHR’s authorization server. The authorize endpoint will run checks based on what the App was registered for and ensure your App correctly follows the authorization process.

Authorization and FHIR Access

Below are the steps for authorization/FHIR Access.

Authorization Request

Your App will construct a request for authorization by adding the following parameters to the query component of the EHR’s “authorize” endpoint URL:

Parameters

An example of an authorization request for an EHR Launch may look something like this (query parameters are separated line by line for clarity):

Once an authorization request is sent to the server, a decision is made by the server on the authenticity of the request (which may additionally request authorization from the end-user). In the context of the FHIR API, this typically means that a user of your App will need to sign-in. Users will need to have their accounts created by the Provider, who controls which Clients/Patients that each User is allowed to see and the scopes of which resources that User is allowed to access.

The EHR will decide whether to grant or deny access. This decision is communicated to your App when the EHR authorization server returns an authorization code (or, if denying access, an error response).

Authorization codes are short-lived and will expire within one minute.

The code will be sent to the “redirect_uri” of your App and includes the following parameters:

Parameters

An example response from the authorization server may look something like this (query parameters are separated line by line for clarity):

Here is the list of error codes for the Authorization endpoint:

Errors

Exchange Code for Access Token

After obtaining an authorization code, your App will trade the code for an access token via a HTTP POST to the EHR authorization server’s token endpoint URL, using content-type “application/x-www-form-urlencoded”.

For a Public App, authentication is not possible, since an App with no secret cannot prove its identity when it issues a call.

For a Confidential App, an Authorization header using HTTP Basic authentication is required, where the username is the App’s “client_id” and the password is the App’s “client_secret”. As an example, if the “client_id” is ‘myclient’ and the “client_secret” is ‘myclientsecret’, then the header uses the value B64Encode(“myclient:myclientsecret”), which converts to bXljbGllbnQ6bXljbGllbnRzZWNyZXQ=.

This gives the request the Authorization header for “Basic Auth” which looks like:

The actual request will be sent using these parameters:

Parameters

An example of this request may look something like this:

The EHR authorization server SHALL return a JSON object that includes an access token or a message indicating that the authorization request has been denied.

The JSON structure for a successful response includes the following parameters:

Parameters

An example response from the code exchange may look something like this:

Here is the list of error codes for the code exchange:

Errors

Using Access Token for Resources

With a valid access token, your App can access protected EHR data by issuing a FHIR API call to one or more of the FHIR endpoint(s) on the EHR’s resource server.

The request includes an Authorization header that presents the access_token as a “Bearer” token (in a real request, {{access_token}} is the actual token you got from the code exchange):

Let’s take a real example to the “Patient” resource using the access_token received in the previous section. We are going to be getting the info for Patient “463”:

See the “Resources” section later in this document for more information on all the Resources, including which parameters to use when calling the Resource.

Here is a list of errors you may see when making a GET request to a Resource:

Errors

Using Refresh Token for new Access Token

Refresh tokens are issued to enable sessions to last longer than the validity period of an access token. With a valid refresh token, your App can request a new access_token by “trading in” the refresh_token to the token endpoint of the EHR’s authorization server.

For a Public App, authentication is not possible, since an App with no secret cannot prove its identity when it issues a call.

For a Confidential App, an Authorization header using HTTP Basic authentication is required, where the username is the App’s “client_id” and the password is the App’s “client_secret”. As an example, if the “client_id” is ‘myclient’ and the “client_secret” is ‘myclientsecret’, then the header uses the value B64Encode(“myclient:myclientsecret”), which converts to bXljbGllbnQ6bXljbGllbnRzZWNyZXQ=.

This gives the App the Authorization token for “Basic Auth” which looks like:

The actual request will be sent using these parameters:

Parameters

An example of this request may look something like this:

If the refresh_token exchange is successful, a JSON object SHALL be returned that includes an access token or a message indicating that the authorization request has been denied.

The JSON structure for a successful response includes the following parameters:

Parameters

An example response from the code exchange may look something like this:

Here is the list of error codes for the refresh_token exchange:

Errors

Bulk Export

App’s that want to export data from an EHR via the FHIR API will need to be registered, setup and have permissions applied to their account for exporting Resources using the Bulk Export process. It is up to the Provider to control which Resources that a particular developer/App will get to export. Providers will also be responsible for setting up “groups” of Clients that the App can use during export requests.

Obtaining Endpoint Information

Your App will need to discover the EHR’s OAuth Bulk Export authorize and token endpoint URLs by querying the “.well-known/smart-configuration” endpoint of the Bulk Server.

Authorization Request

Before your App can request an access token, it SHALL generate a one-time-use JSON Web Token (JWT) that will be used to authenticate your App with the Bulk Export FHIR server. The authentication JWT SHALL include the following claims, and SHALL be signed with your App’s RS384 private key:

Authentication JWT Header Values

After generating an authentication JWT, your App will request a new access token via HTTP POST to the Bulk Export FHIR authorization server’s token endpoint URL, using content-type application/x-www-form-urlencoded with the following parameters:

Parameters

An example of an access token request for the Bulk Export may look something like this (query parameters are separated line by line for clarity):

Once an authorization request is sent to the server, a decision is made by the server on the authenticity of the request. The server will first validate that the client_assertion is a valid JWT, then parse the client_id from the token. Once parsed, the server will use the client_id and attempt to fetch the JWK Set URI that was set up at registration time to decode the JWT. The server will iterate over each RS384 JWK until it finds one that can successfully decode the JWT. If no JWK Set is found or none of the RS384 keys in the JWK Set work, the token will be rejected and an access token will NOT be granted.

If the exchange is successful and the JWT is validated, the server will response with a JSON object that looks like the following:

Bulk Export Access Token Response

An example response may look something like this:

Here is a list of errors that may occur during the authorization/access token exchange:

Errors

Starting the Export Process

With a valid access token, your App can start exporting protected EHR data by issuing a “Group Kickoff Request” with the correct export format.

All export requests will include an Authorization header that presents the access_token as a “Bearer” token (in a real request, {{access_token}} is the actual token you got from the code exchange):

To start the export process, you will first need to issue a “Kickoff Request” for the Export:

In the example above, the app would be requesting an export process for Group # 19. Groups are collections of Client/Patient records which the Provider can assign to your developer account. Once a Kickoff Request is started, each Client/Patient in the Group will be included in the export.

A successful “Kickoff Request” will return a HTTP 202 “Accepted” response with an OperationOutcome FHIR JSON response, which will look like the following:

Each successful request will present a link in the diagnostics where you can go to check the status of the Export.

Here is a list of errors you may see when initiating a Kickoff Request:

Errors

Checking the Status of the Export Process

After initiating a successful Kickoff Request, the response will give you a link where you can go to check the status of the Export request.

In the example below, we are sending a GET request to check the status for Export "t1N0ButfwMSv65PU8X0l" (this will be replaced with the identifier of your unique Export request):

Note that the GET request SHALL contain the Access Token in the authorization header as a “Bearer” token.

Checking the status will return either a HTTP 202 “Accepted” response with an OperationOutcome FHIR JSON response (if the Export is still processing) or a HTTP 200 “OK” response with a JSON structure that will look similar to the example below:

                        
{
“transactionTime":"10/17/2022 05:56:30",
"request":"/Group/test/$export”,
“requiresAccessToken”:true,
“output:[
{
“type”:“Patient”,
“url”:“https://FHIR_ENDPOINT/$exportfilerequest/?_id=t1N0ButfwMSv65PU8X0l&filename=patient.ndjson”
},
{
“type”:“AllergyIntolerance”,
“url”:“https://FHIR_ENDPOINT/$exportfilerequest/?_id=t1N0ButfwMSv65PU8X0l&filename=allergyintolerance.ndjson”
},
…],
“error”:[],
}
                            

In the example above:

• transactionTime: This is the time when the Export process began.
• request: This is the calling Kickoff Request URL that started the Export.
• requiresAccessToken: This boolean indicates if you will be required to provide an access token for each NDJSON “bulkfiles” request. This will always be “true” to enforce security measures before obtaining the NDJSON of an Export.
• output: This is an array of JSON objects, where each object declares the “type” of Resource that is being exported and a URL link to the NDJSON for that export. Each NDJSON link follows this syntax: [groupID]/[resource].ndjson
• error: This array indicates and errors that occurred during the Export.

Here is a list of errors you may see when checking the status of an Export:

Errors

Deleting an Export Process

After initiating a successful Kickoff Request, the App may choose to delete the Export before it has been completed by sending an HTTP DELETE request to the bulkstatus link received from the initial Kickoff Request.

In the example below, we are sending a DELETE request for Export "N6tCp4IJF8WWEzaILmcB" (this will be replaced with the identifier of your unique Export request):

Note that the DELETE request SHALL contain the Access Token in the authorization header as a “Bearer” token.

As an additional note, deleted Export processes CANNOT be recovered. You will need to re-issue a new Kickoff Request in order to start a new Export process (which may involve generating an entirely new Access Token).

Sending a successful DELETE request will return the following OperationOutcome FHIR JSON response:

Here is a list of errors you may see when deleting an Export:

Errors

Obtaining the NDJSON from an Export

Once an Export has been completed, you can use the status link of the Kickoff Request to obtain an array of JSON objects in the “output” field. This array of JSON objects will have their own “type” and “URL” to call to get the NDJSON.

All you need to do is make a GET request to the NDJSON link, with your Access Token in the authorization header as a Bearer token. This will return zero or more JSON objects that are separated by new-line delimiters. The JSON for each Client/Patient in the Export Group will be included in the response. The specifics on each particular Resource is described in more detail in the next section.

Here is a list of errors you may see when making a NDJSON GET request:

Errors

Resources

Below is an overview of each supported FHIR resource, including the parameter list that can be used in each Resource for various data needs. Note that Bulk Export requests will not call the Resource directly but rather receive each JSON response in a NDJSON structure.

Here is a list of errors you may see when making a GET request to a Resource (all Resource’s share a common set of errors):

Errors

Allergy Intolerance

For an example JSON response for Allergy Intolerance, please see the following: AllergyIntolerance.

Profile Details:

• US Core AllergyIntolerance Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific AllergyIntolerance record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Care Plan

For an example JSON response for Care Plan, please see the following: CarePlan.

Profile Details:

• US Core CarePlan Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific CarePlan record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Care Team

For an example JSON response for CareTeam, please see the following: CareTeam.

Profile Details:

• US Core CareTeam Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific CareTeam record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Search Composite OR Summary:

Condition

For an example JSON response for Condition, please see the following: Condition.

Profile Details:

• US Core Condition Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific Condition record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Device (Implantable Device)

For an example JSON response for Implantable Device, please see the following: Device.

Profile Details:

• US Core Implantable Device Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific Device record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Diagnostic Report

This Resource covers Cardiology, Radiology, Pathology and Laboratory Result Reporting.

Profile Details:

• US Core DiagnosticReport Profile for Laboratory Results Reporting
• US Core DiagnosticReport Profile for Report and Note exchange

For an example JSON response for a Cardiology Report, please see the following: Cardiology.

For an example JSON response for a Laboratory Report, please see the following: Laboratory.

1. Diagnostic Report for Laboratory Results

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific DiagnosticReport record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

2. Diagnostic Report for reprot and note exchange

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific DiagnosticReport record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Document Reference

This resource supports the 5 Common Clinical Notes.

Profile Details:

• US Core DocumentReference Profile

For an example JSON response, please see the following: DocumentReference.

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific DocumentReference record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Encounter

For an example JSON response for Encounter, please see the following: Encounter.

Profile Details:

• US Core Encounter Profile

You can retrieve a specific Encounter record “directly” using an Unique ID (like 123, 1234, 12345 etc):

Search Parameter Summary:

Goal

For an example JSON response for Goal, please see the following: Goal.

Profile Details:

• US Core Goal Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific Goal record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Immunization

For an example JSON response for Immunization, please see the following: Immunization.

Profile Details:

• US Core Immunization Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific Immunization record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Location

For an example JSON response for Location, please see the following: Location.

Profile Details:

• US Core Location Profile

This resource is called like the following:

You can retrieve a specific Location record “directly” using an Unique ID (like 123, 1234, 12345 etc):

Medication

For an example JSON response for Location, please see the following: Medication.

Profile Details:

• US Core Medication Profile

This resource is called like the following:

You can retrieve a specific Medication record “directly” using an Unique ID (like 123, 1234, 12345 etc):

This resource does not support any parameters and can only be called directly.

Medication Request

For an example JSON response for MedicationRequest, please see the following: MedicationRequest.

Profile Details:

• US Core MedicationRequest Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific MedicationRequest record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_include” information with any request using the following:

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Search Composite OR Summary:

Observation

This Resource covers Laboratory Result,Blood Pressure,BMI Tests,Head Circumference ,Body Height,Body Weight,Body Temperature,Heart Rate,Prediatric BMI for Age,Pediatric Head Occipital-frontal Circumference Percentile,Pediatric Weight for Height,Pulse Oximetry,Respiratory Rate,Smoking Status.

For an example JSON response for Smoking Status, please see the following: Smoking Status.

For an example JSON response for Pediatric Weight for Height, please see the following: Pediatric Weight for Height.

For an example JSON response for Laboratory Result, please see the following: Laboratory Result.

For an example JSON response for Pediatric BMI for Age, please see the following: Pediatric BMI for Age.

For an example JSON response for Pulse Oximetry, please see the following: Pulse Oximetry.

For an example JSON response for Pediatric Head Occipital-frontal Percentile please see the following: Pediatric Head Occipital-frontal Percentile.

Profile Details:

• US Core DiagnosticReport Profile for Report and Note exchange
• US Core Laboratory Result Observation Profile
• US Core Blood Pressure Profile
• US Core BMI Profile
• US Core Head Circumference Profile
• US Core Body Height Profile
• US Core Body Weight Profile
• US Core Body Temperature Profile
• US Core Heart Rate Profile
• US Core Pediatric BMI for Age Observation Profile
• US Core Pediatric Head Occipital-frontal Circumference Percentile Profile
• US Core Pediatric Weight for Height Observation Profile
• US Core Pulse Oximetry Profile
• US Core Respiratory Rate Profile
• US Core Smoking Status Observation Profile

This resource is called like the following:

You can retrieve a specific Observation record “directly” using an Unique ID (like 123, 1234, 12345 etc):

This resource is called like the following by search:

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Organization

For an example JSON response for Organization, please see the following: Organization.

Profile Details:

• US Core Organization Profile

You can retrieve a specific Organization record “directly” using an Unique ID (like 123, 1234, 12345 etc):

Patient

For an example JSON response for Patient, please see the following: Patient.

Profile Details:

• US Core Patient Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific Patient record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Practitioner

For an example JSON response for Practitioner, please see the following: Practitioner.

Profile Details:

• US Core Practitioner Profile

You can retrieve a specific Organization record “directly” using an Unique ID (like 123, 1234, 12345 etc):

Procedure

For an example JSON response for Procedure, please see the following: Procedure.

Profile Details:

• US Core Procedure Profile

This resource is called like the following:

This resource is called like the following by search:

You can retrieve a specific Procedure record “directly” using an Unique ID (like 123, 1234, 12345 etc):

You can retrieve the “_revinclude” information with any request using the following:

Search Parameter Summary:

Search Parameter Combination Summary:

Provenance

For an example JSON response for Provenance, please see the following: AllergyIntolerance + Provenance Bundle.This is an Allergy Intolerance response with the Provenance attached at the end (in response to a _revincludes parameter).

Profile Details:

• US Core Provenance Profile

You can retrieve a specific Provenance record “directly” using an Unique ID (like 123, 1234, 12345 etc):

This resource does not support any parameters and can only be called directly.