Allscripts FHIR API Introduction

The Allscripts FHIR API allows you to connect to Allscripts products using the FHIR (Fast Healthcare Interoperability Resources) standard for healthcare resources. The FHIR standard enables application developers to create products and exchange clinical data in a secure manner that is consistent, flexible, and easy to implement.

The FHIR standard is constantly evolving. This version of the Allscripts FHIR API supports FHIR release 4 (“R4”) and the United States Core Data for Interoperability (“US Core”) guidelines and requirements for data sharing.

Previous versions of the Allscripts FHIR API were compatible with the DSTU2 release. That version is still available, and the documentation is available separately.

Terminology: applications and products

For the purpose of this documentation, the term “application” refers to a software program connecting to an Allscripts product through the Allscripts FHIR API. The term “product” refers to the Allscripts base system such as Allscripts TouchWorks EHR.

Capability Statement

To get the most up to date information about the Allscripts FHIR API including contact information, the supported FHIR resources, search parameters, and so forth, get a copy of the Allscripts FHIR API Capability Statement.

While the Allscripts FHIR API supports resources and functions that exceed the minimum required for US Core, the final Capability Statement released with R4 in May 2022 describes only the minimum requirements for US Core. It does not describe EHR-specific supported resources and/or search parameters and functions. If an application makes a request that is supported by the Allscripts FHIR API but is not supported by the underlying EHR, the Allscripts FHIR API returns a message indicating that the resource is not supported. The individual EHRs are only required to support the US Core guidelines.

To get a copy of the Allscripts FHIR API capability statement, make the following request:

Resources

The Allscripts FHIR API is a RESTful implementation for an API and is resource-based. The resources are healthcare or related items, such as patients or medications, and all resources have an identifier (_ID) that can be used to access or reference them.

For information on the individual FHIR resources supported by the Allscripts FHIR API and the requests they support, see:

TABLE WITH LINKS TO SWAGGER AND DSTU2 CONTENT

FHIR resources are accessed through HTTP and use the HTTP verbs. For example:

• GET: Retrieve and search for FHIR resources
• POST: Save a new FHIR resource. Do not send an _ID value for the new resource with a POST request. Passing an _ID value indicates to the Allscripts FHIR API that the resource already exists and results in an error.
• PUT: Update a FHIR resource. A PUT request must include the _ID value for the resource. The PUT request also requires an If-Match value in the HTTP header. This is used to validate that the version of the resource in the application that is being updated matches the version in the product database. This prevents conflicting updates.

As required by the FHIR specification, the Allscripts FHIR API supports both JSON and XML formats. By default, the Allscripts FHIR API returns data in JSON. Use the Accept HTTP header to control this format.

• */*: Application accepts anything.
• application/fhir+XML: Response is in XML.
• application/fhir+JSON: Response is in JSON.

Authorization

The Allscripts FHIR API supports the HL7® SMART Application Launch Framework Implementation Guide Release 1.0.0 implementation specification, a profile of the OAuth 2.0 specification. Additionally, the Allscripts FHIR API supports OpenID Connect Core 1.0. For more information on these specifications, see hl7.org/fhir/smart-app-launch/1.0.0/.

The following sections describe the authorization flows for FHIR applications.

Stand-alone application launch for an Allscripts product user

The endpoint for the product's Allscripts FHIR server is available from the Allscripts Endpoint Directory . Endpoints that end in /fhir are for product users.

1. The application requests the Capability Statement from Allscripts FHIR server.
2. The Allscripts FHIR server returns the Capability Statement which includes two endpoints:
   • authorize endpoint for the Allscripts Authorization server
   • token endpoint

   For example:

   “url”: “authorize”,
“valueUri”: “https://.../authorize”
},
{
“url”: “token”,
“valueUri”: “https://.../token”
3. The application sends credentials to the Allscripts Authorization server. These credentials include the application's client ID and client secret. (On the FHIR App page on the ADP portal.)
4. If the application credentials are recognized by the Allscripts Authorization server (meaning the client has authorized the application in the Allscripts License Management Portal), the product's log in screen displays. The user can enter their user credentials (user ID and password) in the product.
   

   If the application credentials are not recognized by the Allscripts Authorization server, the server returns an error.

5. OAuth sends the user's product credentials to the Allscripts Authorization server. If the credentials are valid, the server returns a temporary token to the application's Callback URL (as defined in the ADP portal for the application).
6. The application sends the temporary token to the token endpoint, and the Allscripts Authorization server returns a regular token. The length of time during which the token is valid is defined in the Allscripts License Management Portal.

Stand-alone application launch for a patient

The endpoint for the product's Allscripts FHIR server is available from the Allscripts Endpoint Directory . Endpoints that end in /open are for patient applications.

1. The application requests the Capability Statement from Allscripts FHIR server.
2. The Allscripts FHIR server returns the Capability Statement which includes the authorize endpoint for the Allscripts Authorization server and the token endpoint.
3. The application sends credentials to the Allscripts Authorization server. These credentials include the application's client ID and client secret. (On the FHIR App page on the ADP portal.)
4. If the application credentials are recognized by the Allscripts Authorization server (meaning the client has authorized the application), the server verifies that the patient is valid.

SMART launch

1. An Allscripts product user launches a SMART application from the product. The product sends any relevant context with the launch command to the application.
2. The application requests the Capability Statement from Allscripts FHIR server.
3. The Allscripts FHIR server returns the Capability Statement which includes the authorize endpoint for the Allscripts Authorization server and the token endpoint.
4. Application sends credentials to the Allscripts Authorization server. These credentials include the application's client ID and client secret. (On the FHIR App page on the ADP portal.)
5. If the application credentials are recognized by the Allscripts Authorization server (meaning the client has authorized the application in the Allscripts License Management Portal), the product's log in screen displays. The user can enter their user credentials (user ID and password) in the product. If the application credentials are not recognized by the Allscripts Authorization server, the server returns an error.
6. OAuth sends the user's product credentials to the Allscripts Authorization server. If the credentials are valid, the server returns a temporary token to the application's Callback URL (as defined in the ADP portal for the application).
7. The application sends the temporary token to the token endpoint, and the Allscripts Authorization server returns a regular token. The length of time during which the token is valid is defined in the Allscripts License Management Portal.