Ontada FHIR Server

The Ontada FHIR Server documentation provides information for retrieving patient data from the Common Clinical Data Set, as defined by the 2015 Edition ONC Certification criteria. This documentation is intended to meet applicable certification criteria, as well as aid clients who want to consume these APIs. Access is based on HL7® FHIR® version R4. More information can be found on the FHIR Website.

The Ontada FHIR Server uses OAuth2.0 and Open ID Connect for authentication and authorization.

The /authorize and /token endpoints of the Auth server can be found by calling the /metadata Capability Statement (see documentation) or /.well-known/smart-configuration (see documentation) endpoints.

For more information about registering and launching applications, please reach out to support.

For EHR embedded application launches, clients will use the SMART App Authorization 1.0 specification.

The Ontada FHIR Server also supports Client Credentials for authentication. A client id and secret are passed to the token endpoint to obtain an access token.

practicePublicId

When a token is obtained through client credentials, the client is required to include a header named practicePublicId when calling the APIs. This header must hold the value of the iKnowMed practice that the client is requesting information about. This value is crucial for validation and analytical purposes. It is the same value as the FHIR Organization id field.

The Ontada FHIR Server is a REST-based API implementation. FHIR resources are accessed through HTTP protocol. Data can be retrieved for each resource using search or read APIs. Each search API has its own set of usable query parameters.

Ontada supports the standard JSON and FHIR media type as specified for R4 FHIR.

• application/json+fhir

If no Accept header is included in the request, the media type will default to application/json+fhir.

Ontada supports all FHIR compliant date, date time, and timestamp formats as specified by the R4 FHIR Data Types.

Ontada supports the following HTTP verbs:

• GET

• POST

It is expected most READ/SEARCH options will use a GET verb with query parameters however a POST with x-www-form-urlencoded body parameters is also supported.

FHIR R4 Search Guidelines

With some of the search APIs, the server may return Provenance resources that outline the parties and processes involved in bringing about the resources. They will be included in the end of the Bundle entry list. Including the _revinclude parameter in the query will achieve this in the relevant APIs. You can also retrieve Provenance data by calling the Provenance API directly.

• FHIR R4 Provenance
• FHIR R4 _revinclude

The Ontada FHIR Server undergoes scheduled downtime once a week, typically between 1-3 AM Eastern Time on Sundays. For more details, please contact support.

Below are the common error responses that may be returned by the FHIR Servers. In each case, an OperationOutcome resource will be returned in the response body:

• 400 Bad Request: The server could not understand the request due to invalid syntax.

• 401 Unauthorized: The client must authenticate itself to get the requested response.

• 403 Forbidden: The client does not have access rights to the content.

• 404 Not Found: The server can not find the requested resource.

• 429 Too Many Requests: The client has exceeded the rate limit in requests per second and will receive this response code until usage falls below the rate limit.

• 500 Internal Server Error: The server has encountered a situation it doesn't know how to handle.

FHIR R4 OperationOutcome Resource

Example OperationOutcome response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "diagnostics": "Invalid input"
    }
  ]
}

Consumers of these APIs should follow best practices when making requests. These include, but are not limited to, the following:

• Reuse the access token obtained through client credentials; there is no need to acquire a new token for every API call. The "exp" field in the token indicates when a new token will be required.

• Only call for data that are absolutely needed for the purpose of the application.

• Cache data when possible to avoid unnecessary API calls.

• When applicable, use date ranges to get only the data that are needed.

For precautionary measures, we have implemented API rate limiting. This restricts the number of requests a client can make within a specified time frame. Please reach out to support to learn more.

A client will have certain objectives in what data it needs to retrieve. Here's an overview of the best practices for different types of data retrieval. Further specificity may be found in each search API description in the FHIR Resources section.

Definitions

Active Patient

This is a patient who has an active CarePlan or MedicationRequest in place.

Active Clinical Data

This refers to any clinical information about a patient that is relevant today. It can be either Recent or Historical.

Recent Clinical Data

This includes any clinical information for a patient that was recorded within the last 30 days. For an Active Patient, these data are typically linked to their recent visits. If a patient isn't an Active Patient, it's unlikely that they have any Recent Clinical Data.

Historical Clinical Data

This covers clinical information that was recorded more than 30 days ago. This type of data can come with different labels like draft, active, on-hold, completed, or cancelled.

Best Practices for Searching Clinical Data

Active Clinical Data Best Practice

This practice is for applications that want to access a patient’s current records.

Recent Clinical Data Best Practice

This practice is for applications that want access to recent health records just before, during, or shortly after a patient visit. This practice focuses on capturing all relevant data within this immediate timeframe without targeting specific types of data. This practice timeframe is up to 30 days prior to the current date. An example of using this practice is to query for new lab results of any category or code for a patient that had a visit the previous week.

Targeted Historical Data Best Practice

This practice is for applications aiming to search for historical data. Applications must clearly define the data type (using categories or codes), the precise time period (up to 3 months), or any other relevant qualifiers to narrow the search request, ensuring efficient execution. Historical Clinical Data should be accessed in a limited and focused manner, avoiding broad or extensive searches. For comprehensive patient histories, please consult the Patient Data Export section.

A client that desires to obtain all clinical data for a patient may do so as required by § 170.315(b)(10) Electronic Health Information (EHI) Export. Please see your practice representative for details.

You can use the AllergyIntolerance REST API to read and search for patient AllergyIntolerance FHIR resources.

• The "code" field can be either RxNORM or SNOMED-CT codes.
• An extension showing the SNOMED-CT code of the severity of the allergy or intolerance may be included.
• The reaction manifestation codes will be from SNOMED-CT.

• FHIR R4 AllergyIntolerance Resource
• US Core AllergyIntolerance Profile

The CarePlan APIs provide care plans for a patient. A CarePlan with the SNOMED-CT code "395082007" is considered a cancer care regimen.

A CarePlan with a "status" of "completed" are considered Previous Therapies. A CarePlan with a "status" of "active" are considered Concurrent Therapies.

Line of Therapy and Treatment Plan

The Line of Therapy, staging, and treatment intent can sometimes be found by using regex on the text.div field (see response examples)

The Treatment Plan is found in the "description" field.

• FHIR R4 CarePlan Resource

The CareTeam APIs provide a comprehensive list of practitioners involved in patient care. Each CareTeam resource is dedicated to a single practitioner. Additionally, an extension is incorporated to indicate the patient's preferred pharmacy, which is the same in all resources for a given patient. The resources returned are compliant with the US Core profile.

• FHIR R4 CareTeam Resource
• US Core CareTeam Profile

The Condition APIs provide information about patient conditions. Additionally, an extension is incorporated to indicate whether the Condition is the patient's primary diagnosis (pDX)

Staging and Biomarkers

According to the FHIR specification, the staging of a cancer diagnosis is expected to be documented within the Condition.stage array. However, in this API, the information is represented as an "extension" with the URL "http://fhir.iknowmed.com/StructureDefinition/cds-tools-typedstage" Additionally, biomarkers related to this diagnosis are included in the "contained" list of the Condition resource, as is the Disease State, identified by the code "58DEE57115B24630BCBA0925B5C8D447."

• FHIR R4 Condition Resource
• US Core Condition Profile

The Device APIs provide information about patient implantable devices. The resources returned are compliant with the US Core profile. A custom extension for the date of the device implant may be returned in the base extension list.

• FHIR R4 Device Resource
• US Core Implantable Device Profile