Standardized API Documentation

170.315(g)(7), (g)(9), and (g)(10) STANDARDIZED API DOCUMENTATION

Introduction

EHRYourWay supports standardized API access to patient health data in compliance with the Office of the National Coordinator for Health IT’s (ONC) certification criteria at 45 CFR 170.315(g)(7), 170.315(g)(9), and 170.315(g)(10).

Supported Standards

EHRYourWay implements the following standards for secure access to electronic health information:

CCDA-Based API (170.315(g)(7) and 170.315(g)(9))

• CCDA (Consolidated Clinical Document Architecture) for standardized clinical document exchange
• Supports patient selection and all data request capabilities

FHIR-Based API (170.315(g)(10))

• FHIR R4 – HL7 Fast Healthcare Interoperability Resources for standardized data exchange
• SMART on FHIR – Secure authorization for third-party application access
• Bulk FHIR – Population-level data export for authorized applications

Certification Criteria Covered

• 170.315(g)(7) Patient Selection – API receives patient identification and returns an identifier or token for subsequent data requests
• 170.315(g)(9) All Data Request – API responds to requests for patient data across all U.S. Core Data for Interoperability (USCDI) categories
• 170.315(g)(10) Standardized API for Patient and Population Services – FHIR-based API access for patients, providers, and authorized third-party applications

These capabilities enable patients, healthcare providers, and authorized third-party applications to securely access and exchange electronic health information in a consistent, standardized format.

FHIR-Based API (170.315(g)(10))

FHIR API Documentation: https://ehryourway.com/content/fhir-api-documentation.pdf

FHIR JSON Format URLs: https://ehryourway.com/content/fhir-service-urls.json

SMART on FHIR Application Registration: https://ehryourway.com/3rd-party-app-registration/

CCDA-Based API (170.315(g)(7) and 170.315(g)(9))

Clinical Systems Architecture

Legend

1. Login Request
2. Authenticate Login
3. Request to Web API Handler
4. Response from Handler
5. API Call to Web API Server
6. API Response
7. Data Request to EHR System
8. Clinical Data Access

API Implementation – EHRYourWay Clinical Web API

The EHRYourWay Clinical Web API enables secure and standardized access to patient clinical data in accordance with the ONC 2015 Edition Cures Update certification criteria—specifically 170.315(g)(7) and 170.315(g)(9).

The Clinical Web API allows external applications to authenticate, request, and retrieve clinical data using standard web protocols and security models, as illustrated in the Clinical Systems Architecture above.

A. Overview of Client Interaction

The client interaction with the EHRYourWay Clinical Web API consists of three primary functions:

1. Login – The client logs into the system through the EHRYourWay Authentication Server.
2. Authenticate – The client’s credentials are verified and authenticated by the Web API Server.
3. Access Clinical Data – The authenticated session interacts with the Web API Request Handler to securely access or retrieve clinical data.

B. API Functions and Corresponding ONC Criteria

C. Security Overview

The EHRYourWay Clinical Web API provides multi-layered security to protect patient information and ensure authorized access only. Authentication and authorization are applied at every level of data flow.

• Login Authentication: The Clinical Web API does not handle login authentication directly. Authentication is performed through the EHRYourWay Authentication Server, which validates legitimate client credentials. When a client logs in using their client ID and password, the Authentication Server returns a reference number, valid for a short duration (5 minutes in testing, 2 minutes in production).
• Web API Authentication: The client then submits the client ID and reference number to the Web API Server for secondary validation. Upon successful authentication, the server returns an access token and an external patient ID.
• Request Authentication & Authorization: Every subsequent API call to access clinical data must include the client ID, external patient ID, and access token. Each request is revalidated for authentication before processing. The API enforces HMAC (Hash-Based Message Authentication Code) validation for both headers and payload. Authorization involves verifying the supplied HMAC signature with the server-computed signature to ensure data integrity and request authenticity.

D. EHRYourWay Clinical Web API Terms: https://ehryourway.com/api-terms

E. Software Components & Configurations

The EHRYourWay Clinical Web API is made available as Web Services, using hypertext transmission protocol (http). The requests and responses use JSON payload, i.e. http content-type=”text/plain” or “application/json”.

The EHRYourWay Clinical Web API can be easily accessed using PostMan, or any other software tool or application, capable of sending http requests, and receiving http responses with JSON payload.

API Syntax
The external agent must construct web requests, and invoke the web API provided by EHRYourWay as detailed below. Parameters shown in red, are mandatory.

Web API for Client Login:
Method: POST
URL: https://webcpg.ehryourway.com/EHRAuthenticationServer/api/web/ClientLogin

Request:

{
“ClientId”: “Alicejones”,
        “Password”: “Alicejones123*”
}

Response Sent on Successful Authentication:

{
“ClientId”: “Alicejones”,
“ReferenceNumber”: “5698180926668800”,
“ValidationMessages”: null,
“ValidationStatus”: “Success”
}

Response Sent when Authentication Fails:

{
“ClientId”: ” Alicejones “,
“ValidationMessages”: “Client Login Failed”,
“ValidationStatus”: “Failed”
} 

Web API to Authenticate Client Login:
Method: POST
URL: https://webcpg.ehryourway.com/EHRWebAPIServer/api/web/AuthenticateClientLogin

Request:

{
    “ClientId”: “Alicejones”,
    “ReferenceNumber”: “5698180926668800”
}

Response Sent on Successful Validation

{
  “ClientId”: “Alicejones”,
    “ReferenceNumber”: “5698180926668800”,
    “ExternalPatientId”: “448Alan050119703406”,
    “AccessToken”: “81196298-0585-4438-9494-64ddd8015cd6”,
    “accessTokenExpiryDT”: “2018-07-11T02:31:00”,
    “ValidationMessages”: null,
    “ValidationStatus”: “Success”
}

Response Sent when Validation Fails

{
“ClientId”: “Alicejones”,
“ReferenceNumber”: “56981809266688001”,
“Inner Exception”: “Could not locate Access Token”,
“ValidationMessages”: “Validation of Reference Number Failed.”,
“ValidationStatus”: “Failed”
}

Web API to Get All Patient Clinical Data:

Method: POST

URL: https://webcpg.ehryourway.com//EHRWebAPIRequestHandler/api/web/GetClinicalData

Request:
{
“ClientId”: “Alicejones”,
“ExternalPatientId”: “448Alan050119703406”,
“AccessToken”: “81196298-0585-4438-9494-64ddd8015cd6”,
“Sections”: [ “all” ],
“FromDate”: “06/22/2014”,
“ToDate”: “06/22/2015”,
“ClinicalDataAccessType”: 2
}

Response Sent on Successful Retrieval:

{
“PatientUSCDIAsXml”: “<ClinicalDocument> … </ClinicalDocument>”,
“PatientUSCDIAsReadableFormat”: “https://webcpg.ehryourway.com/EMR_Web_WCF_ClinicalManagement/temp/a6129221e4f94086a1cfac63b6282adf.xml”,
“JSONFormat”: null,
“ValidationStatus”: “Success”,
“ValidationMessages”: null
}

Response Sent when Retrieval Fails: Same as Web API to Get Clinical Data by Category

Exceptions and Error Conditions: 

1. The http status code not equal to 200 (OK), or
2. “ValidationStatus”: “Failed” in the JSON response sent

Conversely a success is indicated by the following conditions:

1. The http status code is equal to 200 (OK), and
2. The response sent should contain “ValidationStatus”: “Success”.

Appendix 1: List of Categories Used in USCDIS Retrieval

Patient Name
Birth Sex
Gender Identity
Sexual Orientation
Address
Phone
Email
Race
Ethnicity
Preferred Language
Date of Birth
Health Insurance Information
Care Team Member(s)
Smoking Status
Health Concerns
Goals
Assessment
Plan of Treatment
Medication Allergies
Problems
Immunizations
Medications
Clinical Tests
Results
Diagnostic Imaging
Vital Signs
Procedures
Implantable Device(s)
Reason For Visit
Encounter
Refer to Consultant(s)
Functional Status
Cognitive Status
History And Physical Exam
Procedure Note
Progress Note
Laboratory Report Narrative
Consultation Note
Discharge Summary Note
Imaging Narrative
Pathology Report Narrative
Provenance

Appendix 2:

Request Generation using HMAC Signatures

The procedure followed for authorizing requests in EHRYourWay Clinical Web API is based on the IETF draft recommendation for signing HTTP Messages. This draft is authored by M. Cavage and M. Sporny, and is available at https://datatracker.ietf.org/doc/draft-cavage-http-signatures/. The HTTP Request generation with HMAC signature is as detailed below.

Step 1: Creation of Signing String

A signing string is created with the following information. The headers used are compiled from the IETF recommendation cited above.

—————————————————–Begin—————————————————————
(request-target): post /EHRWebAPIRequestHandler/api/web/GetClinicalDataByCategory
host: localhost
date: Thu, 12 Jul 2018 10:50:32 GMT
digest: b5f68208531d3d9fcf1d5886341f04404de64fa4d27770e6112c4cd6dfb050bc
content-length: 692
nonce: a209bf19-defb-4e3f-addb-83f50b2ccdbe
x-authorization-timestamp: 1531412432
—————————————————–End—————————————————————–

In the above, digest is the hex string of SHA256 of the httpcontent in UTF-8 format. Nonce is a random uid, and x-authorization-timestamp is Unix time.

Step 2: Sign HMAC-SHA256 Algorithm

The signing string created in Step 1 is signed with HMAC-SHA256 algorithm, using hex string of SHA256 of password as key.

Step 3: Creation of Authorization Header

The Authorization header is created as shown below.

—————————————————–Begin—————————————————————
keyId=”jdonald”,accessToken=”36f0140a-1744-4116-a6db-bd1f6fc2e72c”,
algorithm=”hmac-sha256″,nonce=”a209bf19-defb-4e3f-addb-83f50b2ccdbe”,
headers=”(request-target)%20host%20date%20digest%20content-length%20x-authorization-timestamp”,
signature=”fn6uRwbwq2+bw26Z8ya+SS6lZPSQxZm78iqGoSZcc10=”
—————————————————–End—————————————————————

In the above, keyId is the clientId, accessToken is the access token of the clientId, nonce and headers are from Step 1, signature is base64 string of HMAC signature created in Step 2.

The http request can be generated as shown below.  The following code is in .NET C#, and can be easily converted to other popular languages and platforms.

//***************************************************************************************
//* Variable definitions                                                                *
//***************************************************************************************
string  url = “https://webcpg.ehryourway.com//EHRWebAPIRequestHandler/api/web/GetClinicalData”;

string strPatientInfoReqJson = “ your request json string “;
string strAuthorizationHeader = “ copy authorization header from step-3 above”;
DateTime hdrDate = DateTime.Now();
string  strHost = “webcpg.ehryourway.com”;
string  strDigest = “SHA256 of the content i.e the request json string”;
string  strXAuthTS = “unix time in string format”;
//***************************************************************************************
//* Build request                                                                       *
//***************************************************************************************

// create request
httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, “”);

// set uri

httpRequestMessage.RequestUri = new Uri(url);

// set content

httpRequestContent = new StringContent(strPatientInfoReqJson,
Encoding.UTF8, “text/json”);

httpRequestMessage.Content = httpRequestContent;

// set Authorization header

httpRequestMessage.Headers.Authorization =
new AuthenticationHeaderValue(“Signature”, strAuthorizationHeader);

// set date

httpRequestMessage.Headers.Date = hdrdate;

// set host

httpRequestMessage.Headers.Host = strHost;

// set digest

httpRequestMessage.Headers.Add(“digest”, strDigest);

// set Authentication Timestamp

httpRequestMessage.Headers.Add(“X-Authorization-Timestamp”, strXAuthTS);

// send request to web server

HttpResponseMessage response =
await myClient.SendAsync(httpRequestMessage).ConfigureAwait(false);

Compliance and Certification

The EHRYourWay Clinical Web API has been tested and certified to meet the ONC 2015 Edition Cures Update requirements for:

• §170.315(g)(7) – Patient Selection
• §170.315(g)(9) – All Data Request
• §170.315(g)(10) – Standardized API for Patient and Population Services

This ensures secure, standards-based access for authorized third-party applications and compliance with the U.S. Core Data for Interoperability (USCDI).

Contact Information

For detailed API documentation or developer sandbox access, please contact:

Adaptamed LLC – EHRYourWay
Email: apisolutions@ehryourway.com