Patient Access API Version 1.0

This document discusses Patient Access API Version 1.0 and its methods to connect to the ACI Server and query patient data from EHRs, in the context of meeting the ONC 2015 certification criteria.

Overview

This document discusses Patient Access API Version 1.0 and its methods to connect to the ACI Server to access the Common Clinical Data Set via an API. APIs enable patients to view, download, or transmit their health information using any application of their choice that is configured to meet the technical specifications of the API in the provider's CEHRT.


Terms and Conditions of Use

This section discusses the terms and conditions of using the Patient Access API. The Patient Access API documentation, access link, and materials including Patient Access API support of the FHIR® Specification have been made available to developers for development and testing. The documentation and 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. Use of Patient Access API and access to the material it contains is subject to the following Legal Terms and Conditions as well as to applicable laws. Your access to and browsing of this Web API constitutes your full acceptance of these Legal Terms and Conditions. We reserve the right, at our sole discretion, to update or revise these Legal Terms and Conditions. Please check the Terms and Conditions periodically for changes. Your continued use of this site following the posting of any changes to the Legal Terms and Conditions constitutes acceptance of those changes.
  2. Developers are responsible for maintaining the confidentiality of your logon information, and are fully responsible for all activities that occur under your password or user name. You agree (a) to immediately notify Eye Care Leaders of any unauthorized use of your password or user name or any other breach of security, and (b) to ensure that you exit from your account at the end of each session.
  3. Client applications using the service for API calls require an identifier to connect. Client identifier creation can be accomplished by vendors, in the case of patient-facing applications, or organizations, in the case of provider-facing applications.
  4. Applications must not contain any malware, malicious or harmful code, program, or other internal component (e.g., computer viruses, Trojan horses, “backdoors”) which could damage, destroy, or adversely affect the Patient Access API Platform, services, or other software, firmware, hardware, data, systems, services, or networks.

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 a Patient Access API. This documentation allows applications to query a public-facing API enabled by a data holder/ ACI Server.


Patient Access API Configuration

Pictorial Flow diagram

Detailed steps to begin development of an application with the Patient Access API.

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

Step 2: Patient Application Registration

Patient application registration can be performed using a username, strong password,Application details and ECL Account Number. The end user should obtain these credentials directly from the Patient Portal. The registration information needs to be send to body parameter in Json format:

Request Information

URL
https://[baseURL]/PatientAccessAPI/api/v1/PatientAccessAPI/PatientAppRegistration
Method:
POST
Body Parameters

Patient Application Data: JSON object which used to register an application:

  • PatientApplicationInstanceId (string): Id of the patient application (Not required at the time of registration).
  • ApplicationName (string) (Required): Name of the patient application.
  • ApplicationVersion (string) (Required): Version of the patient application.
  • ApplicationManufacturer (string) (Required): Manufacturer of the patient application.
  • ApplicationManufacturerWebSite (string) (Optional): Web site of the manufacturer of the patient application.
  • ApplicationManufacturerEmail (string) (Optional): Email of the manufacturer of the patient application.
  • ApplicationManufacturerPhoneNumber (string) (Optional): Phone number of the manufacturer of the patient application.
  • DeviceId (string) (Required): Name or identifier of the device where the application is being used.
  • ECLClientAccountNumber (string) (Required): An encoded Identifier of the customer account in ACI module, it will be used to identify the portal customer account.
  • PatientUsername (string) (Required): Username of the patient.
  • PatientPassword (string) (Required): Password of the patient.
  • Latitude (decimal number) (Optional): GPS coordinates provided by the patient application
  • Longitude (decimal number) (Optional): GPS coordinates provided by the patient application

Response Information

HTTP Status Codes
  • 200 OK: The application was registered and the authorization code was generated and sent to the patient.
  • 400 Bad Request: The request is not valid, required information may be missing.
  • 401 Unauthorized: The supplied credentials are incorrect.
Additional Response Information

Along with a 200 OK, the PatientApplication json will be returned.

  • PatientApplicationInstanceId (string): Id of the patient application (required at the time of authorization).
  • ApplicationName (string) : Name of the patient application.
  • ApplicationVersion (string): Version of the patient application.
  • ApplicationManufacturer (string): Manufacturer of the patient application.
  • ApplicationManufacturerWebSite (string): Web site of the manufacturer of the patient application.
  • ApplicationManufacturerEmail (string): Email of the manufacturer of the patient application.
  • ApplicationManufacturerPhoneNumber (string): Phone number of the manufacturer of the patient application.
  • DeviceId (string): Name or identifier of the device where the application is being used.
  • ECLClientAccountNumber (string): An encoded Identifier of the customer account in ACI module, it will be used to identify the portal customer account.
  • PatientUsername (string): Username of the patient.
  • Latitude (decimal number): GPS coordinates provided by the patient application
  • Longitude (decimal number): GPS coordinates provided by the patient application

Along with a 400 Bad Request, additional information will be returned. Possible values:

  • Invalid ECLClientAccountNumber.
  • Required information is missing in the request.

Along with a 401 Unauthorized, additional information will be returned. Possible values:

  • Patient is not active.
  • Patient credentials are invalid.

Step 3: Patient Application Authorization

As the Patient Application registered to the portal, an authorization code will be generated and sent to the patient. Along with authorization code, User Credential and ECL Client Account Number sent to Patient Access API to complete the authorization of the application.

URL
https://[baseURL]/PatientAccessAPI/PatientAppAuthorization
Method:
POST

Request information

Body parameters

AuthorizePatientApplicationjson: json object used to authorize a patient application:

  • ApplicationInstanceId (string) (Required): Id of the patient application (provided by Data holder/ Patent portal in encrypted format, using a NIST certified algorithm).
  • ECLClientAccountNumber (string) (Required): An encoded Identifier of the customer account in ACI module, it will be used to identify the portal customer account.
  • PatientUsername (string) (Required): Username of the patient.
  • PatientPassword (string) (Required): Password of the patient.
  • Latitude (decimal number)(Optional): GPS coordinates provided by the patient application
  • Longitude (decimal number)(Optional): GPS coordinates provided by the patient application
  • AuthorizationCode (string) (Required): Authorization code sent by the portal to the patient with definite expiry time.

Response Information

HTTP status codes
  • 200 OK: The patient application has been authorized.
  • 400 Bad Request: The authorization code is incorrect or is expired.
  • 401 Unauthorized: The request is not valid, required information may be missing or the supplied credentials are incorrect.
Additional Response Information

Along with a 200 OK, API returns success as response

Along with a 400 Bad Request, additional information will be returned. Possible values:

  • Invalid ECLClientAccountNumber.
  • Invalid application ID.
  • The authorization code is incorrect.
  • The authorization code is expired.

Along with a 401 Unauthorized, additional information will be returned. Possible values:

  • Patient is not active.
  • Patient credentials are invalid.

Step 4: Patient Application Authentication

This method will be used to authenticate patient access using an authorized application.

URL
https://[baseURL]/PatientAccessAPIre/PatientAppRegistration
Method:
POST

Request Information

Body parameters

PatientApplicationAuthenticationjson: json object used to authenticate a patient application:

  • ECLClientAccountNumber (string) (Required): An encoded Identifier of the account in the portal.
  • PatientUsername (string) (Required): Username of the patient.
  • PatientPassword (string) (Required): Password of the patient.
  • ApplicationInstanceId (string) (Required): Identifier of the patient application (provided by Data holder/ Patent portal in encrypted format, using a NIST certified algorithm).
  • Latitude (decimal number)(Optional): GPS coordinates provided by the patient application
  • Longitude (decimal number)(Optional): GPS coordinates provided by the patient application

Response Information

HTTP Status Codes
  • 200 OK: The credentials are valid and the application is authorized. As part of a successful response, returns the.
    • PatientId: id of the patient.
    • ProductKey: uniquely identifing the product.
    • PatientAccountNumber: account number of the patient.
    • Token: token generated by API for data request.
  • 400 Bad Request: The request is not valid, required information may be missing.
  • 401 Unauthorized: The supplied credentials are incorrect.
Additional Response Information

Along with a 400 Bad Request, additional information will be returned. Possible values:

  • Invalid ECLClientAccountNumber.
  • Invalid application ID.
  • Along with a 401 Unauthorized, additional information will be returned. Possible values:
  • Patient is not active.
  • Patient credentials are invalid.
  • Unknown application.
  • Application is not authorized.

Step 5: API Details for accessing Patient PHI

After successful authentication of User credentials, now user can access PHI data for the patient, with the search criteria or input by the user through the Patient application.

There are different search criteria or query where Patient Health record can be accessed. Each of them defined in detail:

URL
https://[baseURL]/DataRequest/CCDAdata
Method:
POST

a. Query a Specific Data Category Resource

Common Clinical Data Set Element
ALL DATA
Patient Name
Sex
Date of Birth
Race
Ethnicity
Preferred Language
Smoking Status
Problems
Medications
Medication Allergies
Laboratory Tests
Laboratory Values Results
Vital Signs
Procedures
Care Team Members
Immunizations
Unique Device Identifiers
Assessment and Plan
Goals
Health Concerns

Request Information

Header Parameters
  • Product Key (string) (Required): An encoded unique Product key for an account.
  • Token (Required): Generated by the Patient Access API on the basis of User Credentials.
Body Parameters

PatientApplicationAuthenticationjson: json used to authenticate a patient application:

  • ECLClientAccountNumber (string) (Required): An encoded Identifier of the account in the portal.
  • PatientUsername (string) (Required): Username of the patient.
  • PatientPassword (string) (Required): Password of the patient.
  • SpecificTypes (string) (Required): Data Category Resource.

Response Information

HTTP Status Codes
  • 200 OK: The credentials are valid and the application is authorized. As part of a successful response, return the PHI data in encrypted format (Decryption key and algorithm would be provided by the Patient Access API).
  • 400 Bad Request: The request is not valid, required information may be missing.
  • 401 Unauthorized: The supplied credentials are incorrect.
Additional Response Information

Along with a 400 Bad Request, additional information will be returned. Possible values:

  • Invalid ECL Client Account Number.
  • Invalid User Name or Password.
  • Invalid application ID.

Along with a 401 Unauthorized, additional information will be returned. Possible values:

  • Patient is not active.
  • Patient credentials are invalid.
  • Data Category is not valid.
  • Unknown application.
  • Application is not authorized.

b. Query for a Specific Date or Date Range

Request Information

Header Parameters
  • Product Key (string) (Required): An encoded unique Product key for an account.
  • Token (Required): Generated by the Patient Access API on the basis of User Credentials.
Body Parameters

PatientApplicationAuthenticationjson: json used to authenticate a patient application:

  • ECLClientAccountNumber (string) (Required): Identifier of the account in the portal.
  • PatientUsername (string) (Required): Username of the patient.
  • PatientPassword (string) (Required): Password of the patient.
  • SpecificTypes (string) (Optional): Data Category Resource.
  • FromDate (date string) (Required): From Date for PHI data
  • ToDate (date string) (Optional): To Date till PHI data required.

Response Information

HTTP Status Codes
  • 200 OK: The credentials are valid and the application is authorized. As part of a successful response, return the PHI data in encrypted format (Decryption key and algorithm would be provided by the Patient Access API).
  • 400 Bad Request: The request is not valid, required information may be missing.
  • 401 Unauthorized: The supplied credentials are incorrect.
Additional Response Information

Along with a 400 Bad Request, additional information will be returned. Possible values:

  • Invalid ECL Client Account Number.
  • Invalid User Name or Password.
  • Invalid application ID.

Along with a 401 Unauthorized, additional information will be returned. Possible values:

  • Patient is not active.
  • Patient credentials are invalid.
  • Date Range is not valid.
  • Unknown application.
  • Application is not authorized.

c. Query for All Data as a PHI document

Request Information

Header parameters
  • Product Key (string) (Required): An encoded unique Product key for an account.
  • Token (Required): Generated by the Patient Access API on the basis of User Credentials.
Body Parameters

PatientApplicationAuthenticationjson: json used to authenticate a patient application:

  • ECLClientAccountNumber (string) (Required): Identifier of the account in the portal.
  • PatientUsername (string) (Required): Username of the patient.
  • PatientPassword (string) (Required): Password of the patient.
  • SpecificTypes (string) (Optional): Data Category Resource as All.

Response Information

Http Status Codes
  • 200 OK: The credentials are valid and the application is authorized. As part of a successful response, return the PHI data in encrypted format (Decryption key and algorithm would be provided by the Patient Access API).
  • 400 Bad Request: The request is not valid, required information may be missing.
  • 401 Unauthorized: The supplied credentials are incorrect.
Additional Response Information

Along with a 400 Bad Request, additional information will be returned. Possible values:

  • Invalid ECL Client Account Number.
  • Invalid User Name or Password.
  • Invalid application ID.

Along with a 401 Unauthorized, additional information will be returned. Possible values:

  • Patient is not active.
  • Patient credentials are invalid.
  • Date or Date Range is not valid.
  • Unknown application.
  • Application is not authorized.

Decryption of PHI Data at Application

Patient Access API sends the properly formatted Patient’s Common Clinical Data Set/PHI in an encrypted format and at the application level, the data needs to be decrypted. A standard Symmetric key AES Algorithm is used for Encryption of PHI file. The Symmetric key for decryption is a combination of ECL Account Number and Patient UserName.


Token Expiration

Token expiry time is maintained in configuration file, by default its 30 minutes. If the access token used in the request is invalid, expired, or the user is not authorized to access to the requested Resource, the API will return a 401 Unauthorized HTTP response.


Exception Handling

Exception handling can be done using try-catch blocks for all the API methods and all the exceptions at API level can be logged in the database using NLog.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 Operation Outcome Resource with additional information regarding the issue.


Client Error Format/Structure

Here are the possible error codes, which can come up due to an invalid request

  • Failing to send a required header/json object will result in a 400 Bad Request response.
  • HTTP/1.1 400 Bad Request

  • Requesting a secured API without valid credentials will result in a 401 unauthorized response.
  • HTTP/1.1 401 Unauthorized


Software Components

  • Software must be capable of making HTTPS RESTful requests.
  • Symmetric key AES algorithm

Intended audience

These APIs are intended to patient-facing applications via web and mobile in providing a higher quality of care. Patient should have access to an active patient portal account.