888.455.0855
Facebook-f Linkedin-in

FHIR API Table of Contents

Overview

Easy-to-use JSON-based REST API for InPracSysEHR FHIR. See standard InPracSysEHR API docs here. The InPracSysEHR FHIR API conforms to the R4 specification and the US Core 3.1 Implementation Guide (IG).

Prerequisite

Enable the Standard FHIR service (/fhir/ endpoints) in InPracSysEHR menu: SiteAdmin->FhirSetup->”Enable InPracSysEHR Standard FHIR REST API”

Authorization

InPracSysEHR uses OIDC compliant authorization for API. SSL is required and setting baseurl at SiteAdmin->FhirSetup->’Site Address (required for OAuth2 and FHIR)’ is required.

See Authorization for more details.

FHIR API Documentation

The FHIR API is documented via Swagger. Can see this documentation (and can test it) by going to the swagger directory in your InPracSysEHR installation. The FHIR API is documented there in the fhir section. Standard FHIR endpoints Use https://servicebackup.inpracsysehr.com:8443/ as base URI. Example: https://servicebackup.inpracsysehr.com:8443/r4/Patient returns a Patient’s bundle resource, etc The Bearer token is required for each InPracSysEHR FHIR request (except for the Capability Statement), and is conveyed using an Authorization header. Note that the Bearer token is the access_token that is obtained in the Authorization section. When registering an API client to use with Swagger the following for the redirect url and launch url for the client. Redirect URL -> <base_site_address>/swagger/oauth2-redirect.html Launch URL -> <base_site_address>/swagger/index.html Request:
curl – X GET ‘https://service.inpracsysehr.com:8443/r4/Patient’ \-H ‘Authorization: Bearer eyJ0b2tlbiI6IjAwNnZ3eGJZYmFrOXlxUjF4U290Y1g4QVVDd3JOcG5yYXZEaFlqaHFjWXJXRGNDQUt-FZmJONkh2cElTVkJiaWFobHBqOTBYZmlNRXpiY2FtU01pSHk1UzFlMmgxNmVqZEhcL1ZENlNtaVp
 
-TRFRLMmtsWDIyOFRKZzNhQmxMdUloZmNJM3FpMGFKZ003OXdtOGhYT3dpVkx5b3BFRXQ1
 
-TlNYNTE3UW5TZ0dsUVdQbG56WjVxOVYwc21tdDlSQ3RvcDV3TEkiLCJzaXRlX2lkIjoiZGVmYXVsd-CIsImFwaSI6ImZoaXIifQ==’

Capability Statement

GET fhir/metadata

This will return the Capability Statement. Note this can be tested by going to the url GET ‘https://servicebackup.inpracsysehr.com:8443/metadata’ or sh curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/metadata’

Provenance Resources

Provenance resources are requested by including _revinclude=Provenance:target in the search of a resource. Is currently supported for the following resources:

  • AllergyIntolerance

curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/r4/AllergyIntolerance?_revinclude=Provenance:target’

BULK FHIR Exports

An export operation that implements the BULK FHIR Export ONC requirements can be requested by issuing a GET request to the following endpoints:

  • System Export, requires the system/*.$export scope. Exports All supported FHIR resources

curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/r4/$export’

  • Group Export, requires the system/Group.$export scope. Exports all data in the Patient Compartment for the group. The system automatically creates a group for every Practitioner resource in the system where the patients in the group are the individuals who have the Practitioner as their primary care provider.

curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/r4/Group/1/$export’

  • Patient Export, requires the system/Patient.$export scope. Exports all data for all patients in the Patient Compartment.

curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/r4/Patient/$export’

You will get an empty body response with a Content-Location header with the URL you can query for status updates on the export.

To query the status update operation you need the system/*.$bulkdata-status scope. An example query:

  • Status Query

curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/r4/$bulkdata-status?job=92a94c00-77d6-4dfc-ae3b-73550742536d’

A status Query will return a result like the following:

“transactionTime”: {

 

    “date”: “2021-02-05 20:48:38.000000”,

 

        “timezone_type”: 3,

 

            “timezone”: “UTC”

 

},

 

“request”: “\/apis\/default\/fhir\/Group\/1\/%24export”,

 

    “requiresAccessToken”: true,

 

        “output”: [

 

            {

 

                “url”: “https:\/\/servicebackup.inpracsysehr.com:8443\/r4\/Document\/97552\/Binary”,

 

                “type”: “Patient”

 

            },

 

            {

 

                “url”: “https:\/\/servicebackup.inpracsysehr.com:8443\/r4\/Document\/105232\/Binary”,

 

                “type”: “Encounter”
            }
        ],
            “error”: []
       }

You can download the exported documents which are formatted in Newline Delimited JSON (NDJSON) by making a call to: sh curl -X GET ‘https://servicebackup.inpracsysehr.com:8443/r4/Document/105232/Binary’

In order to download the documents you will need the system/Document.read scope.

Bulk FHIR Scope Reference

  • All System export – system/*.$export system*.$bulkdata-status system/Document.read
  • Group System export – system/Group.$export system*.$bulkdata-status system/Document.read
  • Patient System export – system/Patient.$export system*.$bulkdata-status system/Document.read

3rd Party SMART Apps

InPracSysEHR supports the ability for 3rd party apps who implement the SMART on FHIR App Launch Implementation Guide 1.1.0 context.

3rd party Apps using the confidential app profile are auto enabled if they are strictly a patient standalone app. A patient standalone app is one that only requests patient only scopes such as patient/*. A provider or system app (requesting permissions such as launch, user/*, system/*, etc) must be authorized by the InPracSysEHR Server Installation Administrator. Access Tokens issued to 3rd party apps are only valid for one hour and must be renewed with a refresh token which is  valid for greater than 3 months. Refresh tokens are only issued if offline_access scope is allowed at registration for an individual patient, and authorized by an InPracSys EHR user authenticating with InPracSys EHR through their 3rd party app.

For a patient to have access to their patient data via a 3rd party app they must have api credentials generated by their clinician from the patient demographics page. A patient must not have opted out of 3rd party API access.

InPracSysEHR does NOT support wildcard scopes (patient/. or patient/*.read). Scopes must be requested explicitly by an app at the time of registration. InPracSysEHR does not support adding scopes from the initial registration.

Revoking Clients, Users, Access Tokens, Refresh Tokens

Revoking Clients

You can disable a client completely which prevents their access tokens from being used in the system from the Admin -> System -> API Clients interface. Edit the client registered in your system you wish to disable and hit the Disable button.

Revoking Users

If you wish to revoke a user’s authorization for a particular client you will need to open up the API client from the Admin -> System -> API Clients interface. Once you are editing the client you will need to go to the Authenticated API Users section.

From there you can find the user that is listed and hit the Revoke User button (Note this can be a lengthy list so use your browser’s search text functionality to find the user).

Revoking Access Tokens

You can revoke an access token two ways. One from the API Client edit screen, finding the client and then the access token’s identifier you wish to revoke.

The second way is if you have the fully encoded access token using the API Client Tools screen. Go to Admin->System->API Clients and then click on the Token Tools button. Paste in the entire encoded token and then select Parse Token. Information about the token will be displayed including the authenticated user that authorized the token. Now select the Revoke Token button to revoke the token. Additionally, at the patient’s direction the token will be revoked within 1 hour. A success message will be displayed when the revocation completes. You can parse the token again to see that the token has been revoked.

Native Applications

Interoperability requirements with InPracSysEHR for Native Applications

  • Native applications wishing to use the InPracSysEHR FHIR API with refresh tokens MUST be capable of storing the refresh token in a secure manner similar to the requirements of storing a secret for confidential apps.
  • Native applications must support either PKCE with a public app or use a confidential app. PKCE is still recommended to be used with confidential apps to prevent MITM attacks.
  • Native applications must request the offline_scope in their initial API request in order to receive a refresh token
  • Native application refresh tokens are valid for 3 months before they must be renewed.
  • Native applications will receive a new refresh token every time they are renewed.
  • Native applications can only communicate with InPracSysEHR over a TLS secured channel in order to ensure the safe transmission of the refresh token.
  • Native applications should use certificate pinning to mitigate any SSL MITM attack.
  • Native applications must use the Authorization Code grant flow in order to receive a refresh token.

It is recommended that native applications follow best practices for native client applications as outlined in RFC 8252 OAuth 2.0 for Native Apps.

Carecoordination Summary of Care Docref Operation

Overview Docref

  • The $docref operation is used to request the server to generate a document based on the specified parameters. If no additional parameters are specified then a DocumentReference to the patient’s most current Clinical Summary of Care Document (CCD) is returned. The document itself is retrieved using the DocumentReference.content.attachment.url element. See http://hl7.org/fhir/us/core/OperationDefinition-docref.html for more details.

Details Docref

  • Requires /DocumentReference.$docref, /DocumentReference.read, and /Document.read scopes
  • Start and end date filter encounter related events for the following sections
    • History of Procedures
    • Relevant DX Tests / LAB Data
    • Functional Status
    • Progress Notes
    • Procedure Notes
    • Laboratory Report Narrative
    • Encounters
    • Assessments
    • Treatment Plan
    • Goals
    • Health Concerns Document
    • Reason for Referral
    • Mental Status
  • The following sections have the entire medical record sent to ensure that medical professionals have medically necessary information to provide treatment of care:
    • Demographics
    • Allergies, Adverse Reactions, Alerts
    • History of Medication Use
    • Problem List
    • Immunizations
    • Social History
    • Medical Equipment
    • Vital Signs (shows the latest vitals recorded for the patient)
  • CCD is generated on demand, saved off in patient’s documents record under the documents category.
  • Returns a DocumentReference search bundle per the IG spec.
  • XSL to view the document can be download at //interface/modules/zend_modules/public/xsl/cda.xsl
    • Or xml file can be uploaded as a document into eMedPractice to view in a human readable format
    • Due to browser security restrictions XSL file must be in same directory as ccd document to view.
  • If no start date is provided it will retrieve all records in the patient history up to the end date
  • If no end date is provided it will retrieve all records connected to encounters starting from the start date
  • If a records for a specific service date are desired, make the start date and end date the same day in YYYY-MM-DD format.
  • Dates must be specified in least specifity to most specifity for wildcard like operations IE YYYY for the beginning of the year for start date or ending of the year for end date, YYYY-MM for the beginning of the month for start date and end of the month for end date, etc.

Like many RESTful APIs, the InPracSys FHIR API uses OAuth 2 for security. This means that when making calls to any resource with the InPracSys FHIR API, you must pass a Bearer token. This token is passed in the Authorization Header.

For Developers

FHIR endpoints are of the formats /fhir/r4/{resource} where resource can be patient, allergytolerance, condition etc. which maps to endpoint of the InPracSysEHR FHIR controller which handles the request, and also handles the JSON data conversions.

“GET /fhir/Patient” => function () { RestConfig::authorization_check(“patients”, “demo”); $return = (newFhirPatientRestController())->getAll($_GET); RestConfig::apiLog($return); return$return; }

At a high level, the request processing flow consists of the following steps:

JSON Request -> FHIR Controller Component -> FHIR Validation -> Parsing FHIR Resource -> Standard Service Component -> Validation -> Database

The logical response flow begins with the database result:

Database Result -> Service Component -> FHIR Service Component -> Parse InPracSysEHR Record -> FHIR Controller Component -> RequestControllerHelper -> JSON Response

A state-of-the-art, innovative and complete healthcare IT solution designed to help clinics excel.

888.455.0855  |  HELP@INPRACSYS.COM

This Health IT Module is compliant with the ONC Certification Criteria for Health IT and has been certified by an ONC-ACB in accordance with the applicable certification criteria adopted by the Secretary of Health and Human Services. This certification does not represent an endorsement by the U.S. Department of Health and Human Services.

Additional cost information can be found here.

© 2024 InPracSys. All rights reserved