This document describes QSmartCare’s EHR API Services provided by the FHIR® API Server in QSmartCare. The API Server component supports delivery of API integration capabilities. These products meet the requirements for Certified Electronic Health Records Technology published by Office of the National Coordinator (ONC).

FHIR

Overview

The QSmartCare Complete FHIR API is a Rest API conforming to the R4 specification and the US Core 3.1 Implementation Guide. All API access is over HTTPS. All data is sent and received as JSON. Blank fields are omitted. All timestamps are returned in FHIR® standard date/datetime formats.

Media Types

QSmartCare supports the R4 FHIR standard defined media type for JSON content: application/fhir+json

Root URL

Production root:

Http Method:

GET or POST

[baseURL]

https://fhir.qsmartcare.com:2025/v/r4/sim/

eyJrIjoiMSIsImoiOiIxIiwiYiI6IjE0ODY4MiJ9/fhir

[parameter=value]

patient=148682

FHIR API requests will be made against URLs of the following format.

: [baseURL]/:resource[?:parameters]

Resource

The FHIR standard resource to access.

Example: Patient

https://[baseURL]/Patient?[parameter=value]&[parameter=value]

Parameters

Our API methods take optional parameters.

Resource Identity

Please note that no IDs or Identifiers in the QSmartCare FHIR server are intended to be used outside of the context of their complete URL. A complete URL consists of the service root URL, the resource, and the parameters (if any).

Error Codes

The FHIR server will return standard HTTP Error codes, here are some you might encounter:

(a) A 400 Bad Request response can be received for a variety of reasons such as making a request with an invalid query parameter. For example, searching Patient resource with the “param” query param:

GET [baseURL]/Patient?param=1234

-> HTTP/1.1 400 Bad Request

(b) A 403 Forbidden response is received when making a request the client does not have permissions to make. For example, if your token only allows access to only one Patients resource but you request all Patient’s resources:

GET root URL/Patient

HTTP/1.1 403 Forbidden

(c) A 404 Not Found response can be received when making a request with an invalid or unsupported resource type or if a specific FHIR resource is not found for a certain ID. For example, if you request the “Made Up Resource” that does not exist:

GET root URL/Resource

HTTP/1.1 404 Not Found

(d) A 200 The request was processed appropriately.

GET root URL/Resource

HTTP/1.1 200

(e) A 401 The request did not have a valid authorization token or none was provided. Obtain a valid authorization token and add it to the authorization header.

GET root URL/Resource

HTTP/1.1 401

OperationOutcome

For most errors we will include a response body in the form of an Operation Outcome FHIR resource. You will find more information about the error within the resource in the issue details.

{

"resourceType": "OperationOutcome"

"issue": [

{

"code": "invalid",

"details": {

"text": "Not found"

"severity": "error"

}

Validation

When making create or update requests to the FHIR server the payloads(JWT) will be validated according to the FHIR Release 4 specifications. Any get or search requests will return payloads that conform to the FHIR specifications.

Capability Statement

GET fhir/metadata (https://[baseURL]/metadata)

This will return the Capability Statement. This will be returned in a JSON response.

Service based URL

The main service base endpoint for QSmartCare Complete FHIR API is: (https://[baseURL])

Well Defined Configuration

GET .well-known/smart-configuration

(https://[baseURL]/.well-known/smart-configuration)

This well-defined configuration page for the QSmartCare Complete FHIR can be found at the page listed above. This will be returned in a JSON response.

Authentication

QSmartCare Complete uses OAuth to authenticate the end client according to the HL7 SMART-On-FHIR Implementation Guide. (http://www.hl7.org/fhir/smart-app-launch/index.html)

Launch Sequence

Depending on how your developer account has been setup it will change how you communicate with the API to obtain authorization tokens and subsequently access to the FHIR Resources. Before you can obtain an authorization token, we will need some context of where to retrieve the tokens (such as token endpoints, authorization endpoints, etc.) Below are the ways in which your application can handle initial “kickoff” requests BEFORE authorization tokens are granted.

EHR Launch

Note that you must provide your Launch URI to the Provider during/after account registration in order to perform EHR Launches.

Below are the “context” parameters included in a Launch request to your application:

iss	Required	Identifies the EHR's FHIR endpoint, which your App can use to obtain additional details about the EHR, including its authorization URL, token endpoints, etc.
launch	Required	Opaque identifier for the specific launch. Your App will be required to communicate this value back to the EHR once you are ready to send an authorization request. This will be used to validate the correctness of a valid Launch Authorization request.

An example “Launch Request” that your App can expect to see may look something like this:

https://inferno.healthit.gov/suites/custom/smart/launch?iss= https://[baseURL] /&launch=123

On receiving the launch notification, your App would call the issuer’s (iss) “.well-known/smartconfiguration” endpoint which contains the OAuth authorization and token endpoint URLs to use when requesting authorization to access FHIR resources.

An example “Call” that your App would make after getting the “iss” (where “EHR_FHIR_ENDPOINT” is the “iss” from the launch sequence):

https://[baseURL]/.well-known/smart-configuration

Later, when your App prepares a list of access scopes you want to request from the EHR authorization server, it will be associated with the existing EHR context by including the launch notification in the scope.

Authorization and FHIR Access

Authorization Request

App will construct a request for authorization by adding the following parameters to the query component of the EHR’s “authorize” endpoint URL:

Parameters

response_type	required	Fixed value: code.
client_id	required	This is the Client ID you received at registration.
redirect_uri	required	This is your Redirect URI you gave at registration.
launch	optional	This will be the value you received from the EHR “launch” parameter. Note: This is ONLY used for EHR Launch authorization requests.
scope	required	Each scope will follow the syntax of “[patient \| user]/[resource].read” where [resource] is the name of the Resource, or the “” resource (indicates you wish to have access to ALL Resources). Examples are “patient/Observation.read”, “user/Patient.read”, “patient/.read”, etc. Additionally, you must include either the “launch” scope if you are performing an EHR Launch or the “launch/patient” scope for Standalone launches.
state	required	An unpredictable, opaque value that your App will generate to maintain state between the request and callback. The authorization server includes this value when redirecting back to your App.
aud	required	URL of the EHR resource server. This parameter prevents leaking a genuine bearer token to a counterfeit resource server. In the case of an EHR Launch, this value is the same as the “iss” value received during the Launch sequence.

An example of an authorization request for an EHR Launch may look something like this (query parameters are separated line by line for clarity)

https://

[baseURL]/auth/authorize?response_type=code&client_id=test&redirect_uri=https://inferno.healthit.gov/suites/custom/smart/redirect&scope=launch+openid+fhirUser+offline_access+patient/
Patient.rs&state=c3d55c40-7000-43e7-a38a-bd0a8cd1b27f&aud=[baseURL]&launch=123&code_challenge=pwsmhF7Arq6webfXzx2OhvS27JHB_5RSn4xTV9zhYwE&code_challenge_method=S256

Once an authorization request is sent to the server, a decision is made by the server on the authenticity of the request (which may additionally request authorization from the end-user). In the context of the FHIR API, this typically means that a user of your App will need to sign-in. Users will need to have their accounts created by the Provider, who controls which Clients/Patients that each User is allowed to see and the scopes of which resources that User is allowed to access.

The EHR will decide whether to grant or deny access. This decision is communicated to your App when the EHR authorization server returns an authorization code (or, if denying access, an error response).

An example response from the authorization server may look something like this (query parameters are separated line by line for clarity)

https://[baseURL] /?response_type=code&client_id=test&redirect_uri=https://inferno.healthit.gov/suites/custom/smart/redirect&scope=launch+openid+fhirUser+offline_access+patient/
Patient.rs&state=88451fb9-6157-4776-8fc5-6f3bba70def2&
aud=&launch=123&code_challenge=hBxI1rIDOstcGRtzWtKW8J74IebDeddkX7ypEgqf15o&code_challenge_method=S256&provider=
290&login_type=provider&aud_validated=1&login_success=1

Exchange Code for Access Token

After obtaining an authorization code, your App will trade the code for an access token via a HTTP POST to the EHR authorization server’s token endpoint URL, using content-type “application/x-www-form-urlencoded”.

For a Confidential App, an Authorization header using HTTP Basic authentication is required, where the username is the App’s “client_id” and the password is the App’s “client_secret”. As an example, if the “client_id” is ‘test’ and the “client_secret” is ‘test’, then the header uses the value B64Encode(“test:test”), which converts to

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7Im5lZWRfcGF0aWVudF9iYW5uZXIiOnRydWUsInNtYXJ0X3N0eWxl…

This gives the request the Authorization header for “Basic Auth” which looks like

Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7Im5lZWRfcGF0aWVudF9iYW5uZXIiOnRydWUsInNtYXJ0X3N0eWxlX3VybCI6Imh0…

The actual request will be sent using these parameters:

grant_type	required	Fixed value: authorization_code
redirect_uri	required	Your App’s registered redirect_uri.
client_id	conditional	Required for “public apps”. Omit for “confidential apps”.

An example of this request may look something like this

POST /token HTTP/1.1 Host: EHR_FHIR Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7Im5lZWRfcGF0aWVudF9iYW5uZXIiOnRydWUsInNtYXJ0X3N0eWxlX3VybCI6Imh0…

Content-Type: application/x-www-form-urlencoded grant-type=authorization_code& code=generated_code& redirect_uri= https://redirectURI

The EHR authorization server SHALL return a JSON object that includes an access token or a message indicating that the authorization request has been denied. The JSON structure for a successful response includes the following parameters:

Parameters

access_token	required	The access token issued by the authorization server.
token_type	required	Fixed value: Bearer
expires_in	required	Lifetime in seconds of the access token, after which the token SHALL NOT be accepted by the resource server
scope	required	Scope of access authorized. This list may be different than what was initially requested by the App depending on the exchange between the code and the access token grant. Additionally, there may be permission conflicts which may deny access to scopes versus what was initially requested
id_token	optional	Scope of access authorized. This list may be different than what was initially requested by the App depending on the exchange between the code and the access token grant. Additionally, there may be permission conflicts which may deny access to scopes versus what was initially
refresh_token	required	Token that can be used to obtain a new access token, using the same or a subset of the original authorization grants.
Patient	required	This represents the Client/Patient that was chosen during the authorization process.
smart_style_url	required	This is a URL to the server’s smart_style. Your app may use these colors to design your App to QSmartCare color scheme

An example response from the code exchange may look something like this

{

“access_token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNt…”,

“token_type”: “bearer”,

“expires_in”: 3600,

“scope”: “launch/patient openid fhirUser offline_access patient/Medication.rs patient/AllergyIntolerance.rs patient/CarePlan.rs patient/CareTeam.rs patient/Condition.rs patient/Device.rs patient/DiagnosticReport.rs patient/DocumentReference.rs patient/Encounter.rs patient/Goal.rs patient/Immunization.rs patient/Location.rs patient/MedicationRequest.rs patient/Observation.rs patient/Organization.rs patient/Patient.rs patient/Practitioner.rs patient/Procedure.rs patient/Provenance.rs patient/PractitionerRole.rs”,

“refresh_token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7Im5lZWRfcGF0aWVudF9iYW5uZXIiOnRydWUsInNtYXJ0X3N0eWxlX3VybCI6Imh0dHBzvbi…”,

“patient”:160595,

“smart_style_url” : “https://fhir.qsmartcare.com:3010/smart-style.json”,

“id_token”: “eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlIjoiUGF0aWVudC8xNjA1OTUiLCJmaGlyVXNlciI6IlBhdGllbnQvMTYwNTk1IiwiYXVkIjoidGVzd”

}

Note: All access_token have an expiration date of 3 months from when the token was issued.

Using Access Token for Resources

With a valid access token, App can access protected EHR data by issuing a FHIR API call to one or more of the FHIR endpoint(s) on the EHR’s resource server. The request includes an Authorization header that presents the access_token as a “Bearer” token (in a real request, {{access_token}} is the actual token you got from the code exchange):

Authorization: Bearer {{access_token}}

Using Refresh Token for new access token

Refresh tokens are issued to enable sessions to last longer than the validity period of an access token. With a valid refresh token, your App can request a new access_token by “trading in” the refresh_token to the token endpoint of the EHR’s authorization server.

Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtn…

The actual request will be sent using these parameters:

grant_type	required	Fixed value: refresh_token
refresh_token	required	The refresh token obtained from a successful authorization exchange.
scope	optional	Your App may optionally pass a list of scopes for the new token. Note that the list of scopes must be equal to or a subset of the scopes of the original access_token that you are using a refresh_token for. If you choose not to include this parameter, the new access_token will automatically use all of the scopes of the original access_token.

An example of this request may look something like this:

POST /token HTTP/1.1

POST https://[baseURL]/auth/token

Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtp…

Content-Type: application/x-www-form-urlencoded

grant-type=refresh_token& refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7Im5lZWRfcGF0aWVudF9iYW5uZXIiOnRydWUsInNtYXJ0X3N0eWxlX3VybCI6I…

If the refresh_token exchange is successful, a JSON object SHALL be returned that includes an access token or a message indicating that the authorization request has been denied.

The JSON structure for a successful response includes the following parameters:

access_token	required	The new access token issued by the authorization server.
token_type	required	Fixed value: Bearer
expires_in	required	Lifetime in seconds of the access token, after which the token SHALL NOT be accepted by the resource server.
scope	required	Scope of access authorized. This list may be different than what was in the original access_token before the refresh, depending on the optional scopes that may have been passed during the refresh request
id_token	optional	Authenticated patient identity and user details, if requested in the scopes (open_id and fhirUser scopes must both be requested for an id_token to be issued).
refresh_token	required	Token that can be used to obtain another new access token once this new access_token expires
patient	required	This represents the Client/Patient that was extracted from the refresh_token.
smart_style_url	required	This is a URL to the server’s smart_style. Your app may use these colors to design your App to QSmartCare color scheme.

An example response from the code exchange may look something like this:

{

“access_token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtY…”,

“token_type”: “bearer”,

“expires_in”: 3600,

“refresh_token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7Im5lZWRfcGF0aWVudF9iYW5uZXIiOnRydWUsInNtYXJ0X3N0eWxlX3VybCI6Imh0dHBzOi8vZmhpci

”,

“patient”:160595,

“smart_style_url” : “https://fhir.qsmartcare.com:3010/smart-style.json”,

“id_token”: “eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlIjoiUGF0aWVudC8xNjA1OTUiLCJmaGlyVXNlciI6IlBhdGllbnQvMTYwNTk1IiwiYXVkIjoidGVzdC”

}

Bulk Data

App’s that want to export data from an EHR via the FHIR API will need to be registered, setup and have permissions applied to their account for exporting Resources using the Bulk Export process. It is up to the Provider to control which Resources that a particular developer/App will get to export. Providers will also be responsible for setting up “groups” of Clients that the App can use during export requests. The Bulk Export server is separate from the EHR Launch/Standalone Patient App server.

Note: To use the Bulk Export process, App must be able to protect a private/secret key!

App also must register a JWK set with at least one JWK in the RS384 format, which includes an “n” and “e” value pair (modulus and exponent).

Obtaining Endpoint Information

App will need to discover the EHR’s OAuth Bulk Export authorize and token endpoint URLs by querying the “.well-known/smart-configuration” endpoint of the Bulk Server.

Authorization Request

Before the App can request an access token, it shall generate a one-time-use JSON Web Token (JWT) that will be used to authenticate your App with the Bulk Export FHIR server. The authentication JWT shall include the following claims, and shall be signed with your App’s RS384 private key:

Authentication JWT Header Values

Alg	required	The algorithm (RS384) used for signing the authentication JWT.
kid	required	The identifier of the key-pair used to sign this JWT. This identifier SHALL be unique within your App’s JWK Set.

After generating an authentication JWT, your App will request a new access token via HTTP POST to the Bulk Export FHIR authorization server’s token endpoint URL, using content-type application/x-www-form-urlencoded with the following parameters:

Parameters

scope	required	The scope of access requested. Each scope will follow the syntax of “system/[resource].read” where [resource] is the name of the Resource you want to export, or the “*” resource (indicates you wish to export ALL Resources).
grant_type	required	Fixed value: client_credentials
client_assertion_type	required	Fixed value: urn:ietf:params:oauth:client-assertiontype:jwt-bearer
client_assertion	required	Your generated and signed JWT using the RS384 format.

An example of an access token request for the Bulk Export may look something like this (query parameters are separated line by line for clarity):

https://[baseURL]/auth/token/

scope=system/*.read&

grant_type=client_credentials&

client_assertion_type= urn:ietf:params:oauth:client-assertion-type:jwt-bearer& client_assertion=DeveloperJWT

Once an authorization request is sent to the server, a decision will be made by the server on the authenticity of the request. The server will first validate the client_assertion is a valid JWT, then parse the client_id from the token. Once parsed, the server will use the client_id and attempt to fetch the JWK Set URI that was set up at registration time to decode the JWT. The server will iterate over each RS384 JWK until it finds one that can successfully decode the JWT. If no JWK Set is found or none of the RS384 keys in the JWK Set work, the token will be rejected and an access token will NOT be granted.

If the exchange is successful and the JWT is validated, the server will respond with a JSON object that looks like the following:

Bulk Export Access Token Response

access_token	required	The access token issued by the Bulk Export Authorization.
token_type	required	Fixed value: bearer
expires_in	required	The lifetime in seconds of the access token. This will always be 300, for a five minute token lifetime.
scope	required	The lifetime in seconds of the access token. This will always be 300, for a five minute token lifetime.

An example response may look something like this

{

“access_token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtY”,

“token_type”: “bearer”,

“expires_in”: 3600,

“scope”: “system/*.read”

}

Starting Export Process

With a valid access token, your App can start exporting protected EHR data by issuing a “Group Kickoff Request” with the correct export format.

All export requests will include an Authorization header that presents the access_token as a “Bearer” token (in a real request, {{access_token}} is the actual token you got from the code exchange):

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtY…

To start the export process, you will first need to issue a “Kickoff Request” for the Export:

GET: https:// [baseURL] /Group/QSMEHRGROUP/$export

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtYXJ…

In the example above, the app would be requesting an export process for Group # 1. Groups are collections of Client/Patient records which the Provider can assign to your developer account. Once a Kickoff Request is started, each Client/Patient in the Group will be included in the export.

A successful “Kickoff Request” will return a HTTP 202 “Accepted” response with an OperationOutcome FHIR JSON response, which will look like the following:

{

"resourceType": "OperationOutcome",

"text": {

"status": "generated",

"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight:bold;\">information</td><td>[]</td><td><pre>Your request has been accepted. You can check its status at https:// [baseURL]/bulkstatus/9e3add49a51f1b666c9286aa4352c575"</pre></td></tr></table></div>"

"issue": [

{

"severity": "information",

"code": "processing",

"diagnostics": "Your request has been accepted. You can check its status at \"https://[baseURL]/bulkstatus/26962a694f5909d8e9a6e617f7604aa5

\""

}

]

}

Checking status of Export Process

After initiating a successful Kickoff Request, the response will give you a link where you can go to check the status of the Export request.

In the example below, we are sending a GET request to check the status for Export #89 (this will be replaced with the identifier of your unique Export request):

GET: /fhir/bulkstatus/300c1870caf49545fa3a48e37e655d30 HTTP/1.1

Host: https://[baseURL]

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucbnQucnMgcTR9…

Note that the GET request SHALL contain the Access Token in the authorization header as a “Bearer” token.

Checking the status will return either a HTTP 202 “Accepted” response with an OperationOutcome FHIR JSON response (if the Export is still processing) or a HTTP 200 “OK” response with a JSON structure that will look like the example below:

{

"transactionTime": "1668509577760",

"request": "https:// [baseURL]/eyJlcnIiOiIiLCJwYWdlIjoxMDAwMCwiZHVyIjoxMCwidGx0IjoxNSwibSI6MSwic3R1Ijo0LCJkZWwiOjB9/fhir/Group/QSMEHRGROUP/$export",

"requiresAccessToken": true,

"output": [

{

"type": "AllergyIntolerance",

"count": 2,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Miwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.AllergyIntolerance.ndjson"

{

"type": "CarePlan",

"count": 2,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Miwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.CarePlan.ndjson"

{

"type": "CareTeam",

"count": 2,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Miwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.CareTeam.ndjson"

{

"type": "Condition",

"count": 5,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NSwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Condition.ndjson"

{

"type": "Device",

"count": 3,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Mywic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Device.ndjson"

{

"type": "DiagnosticReport",

"count": 4,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NCwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.DiagnosticReport.ndjson"

{

"type": "DocumentReference",

"count": 2,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Miwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.DocumentReference.ndjson"

{

"type": "Encounter",

"count": 2,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Miwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Encounter.ndjson"

{

"type": "Goal",

"count": 3,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Mywic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Goal.ndjson"

{

"type": "Immunization",

"count": 2,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6Miwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Immunization.ndjson"

{

"type": "MedicationRequest",

"count": 5,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NSwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.MedicationRequest.ndjson"

{

"type": "Observation",

"count": 25,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6MjUsInNlY3VyZSI6dHJ1ZX0/fhir/bulkfiles/1.Observation.ndjson"

{

"type": "Organization",

"count": 1,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6MSwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Organization.ndjson"

{

"type": "Patient",

"count": 4,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NCwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Patient.ndjson"

{

"type": "Practitioner",

"count": 5,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NSwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Practitioner.ndjson"

{

"type": "Procedure",

"count": 5,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NSwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Procedure.ndjson"

{

"type": "Provenance",

"count": 4,

"url": "https:// [baseURL]/eyJpZCI6IjMwMGMxODcwY2FmNDk1NDVmYTNhNDhlMzdlNjU1ZDMwIiwib2Zmc2V0IjowLCJsaW1pdCI6NCwic2VjdXJlIjp0cnVlfQ/fhir/bulkfiles/1.Provenance.ndjson"

}

"deleted": [],

"error": []

}

In the example above:

✔ transactionTime: This is the time when the Export process began.

✔ request: This is the calling Kickoff Request URL that started the Export.

✔ requiresAccessToken: This boolean indicates if you will be required to provide an access token for each NDJSON “bulkfiles” request. This will always be “true” to enforce security measures before obtaining the NDJSON of an Export.

✔ output: This is an array of JSON objects, where each object declares the “type” of Resource that is being exported and a URL link to the NDJSON for that export. Each NDJSON link follows this syntax: [groupID]/[resource].ndjson

✔ deleted: This array indicates if the Export was deleted before it could be completed.

✔ error: This array indicates and errors that occurred during the Export.

Deleting Export Process

After initiating a successful Kickoff Request, the App may choose to delete the Export before it has been completed by sending an HTTP DELETE request to the bulkstatus link received from the initial Kickoff Request.

In the example below, we are sending a DELETE request for Export #89 (this will be replaced with the identifier of your unique Export request):

DELETE /fhir/bulkstatus/300c1870caf49545fa3a48e37e655d30 HTTP/1.1

Host: https://[baseURL]

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjp0cnVlLCJzbWFydF9zdHlsZV91cmwiOiJodHRwczovL2ZoaXIucXNtYXJ0Y4MT…

Note that the DELETE request SHALL contain the Access Token in the authorization header as a “Bearer” token.

As an additional note, deleted Export processes CANNOT be recovered. You will need to reissue a new Kickoff Request to start a new Export process (which may involve generating an entirely new Access Token).

Sending a successful DELETE request will return the following OperationOutcome FHIR JSON response:

{

“resourceType”: “OperationOutcome”,

“text”: {

“status”: “generated”

“issue”: [

{

“severity”: “information”,

“code”: “processing”,

“diagnostics”: "Export request has been cancelled."

}

]

}

Obtaining the NDJSON form Export

Once an Export has been completed, you can use the status link of the Kickoff Request to obtain an array of JSON objects in the “output” field. This array of JSON objects will have their own “type” and “URL” to call to get the NDJSON. All you need to do is make a GET request to the NDJSON link, with your Access Token in the authorization header as a Bearer token. This will return zero or more JSON objects that are separated by new-line delimiters. The JSON for each Client/Patient in the Export Group will be included in the response. The specifics on each particular Resource is described in more detail in the next section.

Resources

Allergy Intolerance

The Allergy Intolerance resource provides a bundle of allergies for a given patient resource. An example of retrieving Allergy Intolerance records is included below. An example of retrieving Allergy Intolerance records is included below.

Get allergy intolerances associated with a specific patient

GET https://[baseURL]/AllergyIntolerance?[parameter=value]

Care Plan

Care Plan is the recorded plan of one or more practitioners to deliver care for a patient, group, or community; this is often related to the treatment of a specific condition or set of conditions. An example of retrieving care plan is included below.

Get Care Plan associated with a specific patient

GET https:// [baseURL]/CarePlan?category=assess-plan&[parameter=value]

Care Team

The Care Team resource identifies the different members of a patient’s care team, and the role that these members play in caring for the patient. A patient may have multiple care teams. An example of retrieving care team records is included below.

Get Care Teams related to a specific patient
GET https://[baseURL]/CareTeam?[parameter=value]

Find Care Teams using a patient ID and status of the care team

GET
https://[baseURL]/CareTeam?[parameter=value]&status=active

Condition

Condition resources identify a condition, diagnosis, or other clinical concept that has risen to a level of concern. Examples of API calls for condition resources are shown below:

Get conditions associated with a specific patient

GET https://[baseURL]/Condition?[parameter=value]

Device (Implantable Device)

Device resources represent items used in the provision of healthcare, including medical devices such as durable (reusable) medical equipment, implantable devices, as well as disposable equipment used for diagnostic, treatment, and research. Specifically, resources for implantable devices use the US Core Implantable Device profile. Examples of API requests to retrieve device data are shown below:

Get implantable devices associated with a specific patient

GET https://[baseURL]/Device?[parameter=value]

Diagnostic Report

The Diagnostic Report resource is used to summarize findings and test results from labs, imaging, and other diagnostics. Examples of API requests for diagnostic report resources are shown below:

Get Diagnostic Reports related to a specific patient

GET
https://[baseURL]/DiagnosticReport?[parameter=value]

Find by patient ID and category of report

GET https://fhir.qsmartcare.com:2025/v/r4/sim/eyJrIjoiMSIsImoiOiIxIiwiYiI6IjE0ODY4MiJ9/fhir/DiagnosticReport?category=LP29684-5&patient=148682

Document Reference

The Document Reference resource identifies the location of a clinical note, image, or PDF related to a patient. This is used as a pointer to the location of the document: the actual content is stored elsewhere and will need to be accessed separately. Example API requests for a specific document, as well as to see all the documents associated with a particular patient, are shown below:

Get using DocumentReference ID

GET
https://[baseURL]/DocumentReference?[parameter=value]

Retrieve all document references related to a patient

GET
https://[baseURL]/DocumentReference?[parameter=value]

Find by Patient ID, category and date search parameters

GET
https://[baseURL]/DocumentReference?[parameter=value]

Goal

The Goal resource represents a desired health state to be achieved for a patient, for example weight loss or restoring activities of daily living. This resource can also apply to a group of patients or an organization. However, here at One Medical, the Goal resource will primarily be used for patient goals. Example API requests for goal records are shown below

Retrieve all goals related to a patient
GET
https://[baseURL]/Goal?[parameter=value]

Immunization

Each Immunization resource identifies an immunization performed on a patient. A bundle of these resources together can be used to represent the immunization history of the patient. Example API requests for immunization records are shown below:

Retrieve all immunizations related to a patient

GET https://[baseURL]/Immunization?[parameter=value]

Medication Request

The Medication Request resource covers medication orders for a patient. This includes both inpatient and outpatient orders related to medications.

Retrieve all medication requests related to a patient

GET

https://[baseURL]/MedicationRequest?intent=proposal&[parameter=value]

Observation

This Resource covers Smoking Status, Pediatric Weight for Height, Laboratory Result, Pediatric BMI for Age, Pulse Oximetry, Pediatric Head Occipital-frontal Percentile, Vital Signs (Body Height, Body Temperature, Blood Pressure, Body weight, Heart Rate and Respiratory Rate)

Example requests for observation data are shown below:

Retrieve observations related to a patient

Smoking

Get Smoking related to a specific patient

GET https://[baseURL]/Observation? [parameter=value]&[parameter=value]

Pediatric weight

Get Pediatric weight related to a specific patient

GET https://[baseURL]/Observation? [parameter=value]&[parameter=value]

Laboratory Result

Get Laboratory Result related to a specific patient

GET https://[baseURL]/Observation?category=laboratory&[parameter=value]

Pediatric BMI for Age

Get Pediatric BMI for Age related to a specific patient

GET https://[baseURL]/Observation? [parameter=value]&[parameter=value]

Pulse Oximetry

Get Pulse Oximetry related to a specific patient

GET https://[baseURL]/Observation? [parameter=value]&[parameter=value]

Pediatric Head Occipital-frontal Percentile

Get Pediatric Head Occipital-frontal Percentile related to a specific patient

GET https://[baseURL]/Observation? [parameter=value]&[parameter=value]

Vital Signs

GET https://[baseURL]/Observation? [parameter=value]&[parameter=value]

Procedure

The Procedure resource type identifies procedures performed on a patient, including surgical procedures, diagnostic procedures, biopsies, counseling, etc. Example API requests for procedure data are shown below:

Get all procedures performed on a patient

GET https://[baseURL]/Procedure?[parameter=value]

Find specific procedure by patient ID, and date

GET https://[baseURL]/Procedure? [parameter=value]&[parameter=value]

Encounter

This is the recorded interaction between a patient and a healthcare provider for the purpose of receiving healthcare services or a health assessment.

Get all Encounters performed on a patient

GET https://[baseURL]/Encounter/[parameter=value]

Organization

This resource records a formally or informally recognized group of people (or organizations) formed for the purpose of achieving a collective action.

Get all Organization

GET

https://[baseURL]/Organization/[parameter=value]

Practitioner

This resource records the person who is directly or indirectly involved in the provisioning of healthcare. For in patient clinics, this is typically the physician or nurse attending to a patient.

GET https://[baseURL]/Practitioner/[parameter=value]

Provenance

The Provenance resource tracks information about the activity that created date and time or signed note and the physician involved.

GET

https://[baseURL]/Provenance/[parameter=value]

Terms of Use

The Quality Surgical Management ("QSmartCare ") public web site, including but not limited to www.QSMARTCARE.org, (the "Public Site") and QSmartCare secure web sites, including but not limited to our Customer Secure Site and Business Alliance Program Secure Site (the "Secure Sites") (the Public Site and the Secure Sites collectively hereinafter referred to as the "Site") are owned and operated by QSmartCare. These Terms of Use ("TOU") may be changed from time to time and without further notice. Your continued use of the Site after any such changes constitutes your acceptance of the new terms. If you do not agree to abide by these or any future terms, please do not use the Site or download materials from it. QSmartCare may terminate, change, suspend, or discontinue any aspect of the Site, including the availability of any features, at any time. QSmartCare may remove, modify, or otherwise change any content, including that of third parties, on or from this Site. QSmartCare may impose limits on certain features and services or restrict your access to parts or the entire Site without notice or liability. QSmartCare may terminate your use of the Site at any time in its sole discretion. These terms apply exclusively to your access to and use of the Site and do not alter the terms or conditions of any other agreement you may have with QSmartCare.

Proprietary Rights. Copyrights. All content on the Site, including but not limited to design, text, software, technical drawings, configurations, graphics, other files, and their selection and arrangement are either Copyright by QSmartCare, or are the property of QSmartCare affiliates or licensors. All rights reserved.

Trademarks. All trademarks on the Site are either trademarks or registered trademarks of QSmartCare or its affiliates or licensors and may not be copied, imitated, or used, in whole or in part, without the prior written permission of QSMARTCARE. All page headers, custom graphics, button icons, and scripts are service marks, trademarks and/or trade dress of QSMARTCARE or its affiliates, and may not be copied, imitated, or used, in whole or in part, without the prior written permission of QSMARTCARE. Other trademarks, registered trademarks, product names, and company names or logos displayed on the Site are the property of their respective owners.

Patents. QSmartCare products and processes are covered by one or more patents and are subject to other trade secret and proprietary rights. QSmartCare reserves all such rights. No transfer or grant of rights under any patents is made or is to be implied by any provision of these TOU. You agree not to infringe upon such rights or decompile, reverse engineer, or disassemble any of QSmartCare products or processes.

Software. Any software, including any files, images generated by the software, code, and data accompanying the software (collectively, the "Software"), used or accessible through this Site may be used by you solely for accessing and using this Site for purposes expressly stated on the Site, provided that such uses are not competitive with or derogatory to QSmartCare. QSmartCare retains full and complete title to and all intellectual property rights in the Software. You agree not to copy, distribute, sell, modify, decompile, reverse engineer, disassemble or create derivative works from any Software.

User conduct – General (In using this site you agree)

a) not to disrupt or interfere with the security of, or otherwise abuse, the Site, or any services, system resources, accounts, servers, or networks connected to or accessible through the Site or affiliated or linked Web sites

b) not to disrupt or interfere with any other user's enjoyment of the Site or affiliated or linked Web sites

c) not to upload, post, or otherwise transmit through or on this Site any viruses or other harmful, disruptive, or destructive files

d) not to use or attempt to use another's account, service, or system without authorization from Greenway, or create or use a false identity on this Site

e) not to transmit through or on this Site spam, chain letters, junk mail or any other type of unsolicited mass email to people or entities who have not agreed to be part of such mailings.

f) not to divulge your username and password to others either on or off the Site

g) not to attempt to obtain unauthorized access to the Secure Sites; and

h) not use this Site to seek, provide, or obtain specific medical advice, medical opinion, diagnosis, or treatment as applied to a patient's particular condition or situation.

In addition, you agree that you are solely responsible for actions and communications undertaken or transmitted under your account, and that you will comply with all applicable local, state, national, and international laws and regulations, including but not limited to United States export restrictions, that relate to your use of or activities on this Site. This Site is controlled and operated in the United States. If you are in a jurisdiction that restricts you from accessing this Site, do not access or use this Site. QSmartCare makes no representation that the Site is appropriate or available for use outside the United States.

Privacy Policy

You acknowledge and agree that QSmartCare may use the data collected in the course of our relationship for the purposes identified in our Privacy Policy, which is incorporated by reference as if fully set forth in these TOU.

Customer Secure Site

Only QSmartCare Customers are allowed access to the QSmartCare Customer Secure Site. The terms of this Section 4 apply to Customers accessing the Customer Secure Site. Access to the Customer Secure Site is subject to these TOU and the terms of your software and/or services agreement (your "Agreement"). You agree that the Customer Secure Site contains Confidential Information as defined in your Agreement and that you will treat such Confidential Information in accordance with the terms of your Agreement. By posting messages or uploading files or templates through the Customer Secure Site, you are granting QSmartCare a royalty-free, perpetual, non-exclusive, unrestricted, worldwide license to:

1. use, copy, sublicense, adapt, and transmit; and

2. sublicense to third parties the unrestricted right to exercise any of the foregoing rights granted. This includes the right to exploit any proprietary rights in such templates, files, or messages, including but not limited to rights under copyright, trademark, service mark or patent laws under any relevant jurisdiction. Files or templates you download from the Customer Secure Site are not warranted by QSmartCare and are not guaranteed to be accurate or up to date.

Links and Third-Party Content

This Site may from time to time contain links to other Web sites. These links are provided as a convenience and do not constitute an endorsement, sponsorship, or recommendation by QSmartCare of -- or responsibility for -- the linked Web sites or any content, services, or products available on or through such sites. Links from Other Web Sites. All links to this Site must be approved in writing by QSmartCare, except that QSmartCare consents to links in which:

a. the link is a text-only link containing only the title of the home page of this Site

b. the link "points" only to the home page of the Site and not to deeper pages

c. the link, when activated by a user, displays this home page of the Site full-screen and not within a "frame" on the linked Web site, and

d. the appearance, position, and other aspects of the link does not

1. create the false appearance that an entity or its activities or products are associated with or sponsored by QSmartCare or its affiliates, or

2. be such as to damage or dilute the goodwill associated with the name and trademarks of QSmartCare or its affiliates. QSmartCare reserves the right to revoke this consent to link at any time in its sole discretion.

Third-Party Content. This Site may from time to time contain material, data, or information provided, posted, or offered by third parties, including but not limited to advertisements or postings in online community discussions. You agree that neither QSmartCare nor its affiliates shall have any liability whatsoever to you for any such third-party material, data, or information.

Disclaimers

This site and the content available through it are provided on an "as is" and "as available" basis. You expressly agree that use of this site and/or its content is at your sole risk. To the fullest extent permissible pursuant to applicable law, QSmartCare and its affiliates disclaim all warranties of any kind, whether express or implied, including without limitation any warranty of merchantability, fitness for a particular purpose, or non-infringement. You expressly agree that use of this site, including all content, data, or software distributed by, downloaded, or accessed from or through the site, is at your sole risk. You understand and agree that you will be solely responsible for any damage to your business, your computer system, or loss of data that results from the download of such content, data, and/or software. You acknowledge that QSmartCare does not control information, products, or services offered by third parties through the site. Except as otherwise agreed in writing, QSmartCare and its affiliates assume no responsibility for and make no warranty or representation as to the accuracy, currency, completeness, reliability or usefulness of any advice, opinion, statement, or other content or of any products or services distributed or made available by third parties through the site. QSmartCare does not make any warranty that this site or its content will meet your requirements, or that this site or its content will be uninterrupted, timely, secure, or error free, or that defects, if any, will be corrected. Nor does QSmartCare make any warranty as to the results that may be obtained from use of this site or its content or as to the accuracy, completeness, or reliability of any information obtained through use of this site. QSmartCare assumes no responsibility for any damages suffered by a user, including, but not limited to, loss of data from delays, non-deliveries of content or email, errors, system down time, mis deliveries of content or email, network or system outages, file corruption, or service interruptions caused by the negligence of QSmartCare, its affiliates, its licensors, or a user's own errors and/or omissions. Except as specifically provided herein, QSmartCare disclaims any warranty or representation that confidentiality of information transmitted through the site will be maintained. No advice or information, whether oral or written, obtained by you from QSmartCare or through the site shall create any warranty not expressly stated in writing.

Limitation of Liability

Under no circumstances, including, without limitation, negligence, shall QSmartCare or its parents, subsidiaries, affiliates, officers, directors, employees, agents, or suppliers be liable for any direct, indirect, incidental, special, or consequential damages arising from or in connection with the use of or the inability to use this site or any content contained on the site, or resulting from unauthorized access to or alteration of your transmissions or data, or other information that is sent or received or not sent or received, including but not limited to, damages for loss of profits, use, data or other intangibles, even if QSmartCare has been advised of the possibility of such damages. The parties acknowledge that this is a reasonable allocation of risk

General

Applicable Law. These TOU shall be governed by and construed in accordance with the laws of the State of Florida, and the federal laws of the United States of America, without giving effect to its conflict of law’s provisions. You agree to submit to the personal and exclusive jurisdiction of the state or federal courts located within the State of Florida.

Other

These TOU constitute the entire agreement between you and QSmartCare governing your use of the Site. Should any provision in these TOU be found invalid or unenforceable for any reason, then that provision shall be deemed severable from the terms and shall not affect the validity or enforceability of the remaining provisions. You agree that any claim arising out of or related to the terms, or your use of the Site must be filed within one year after it arose or be permanently barred.

Privacy Policy

We at Magilen Enterprises Inc. are committed to maintaining the privacy and security of our customers’ personal information on www.qsmartcare.com Through this privacy statement, QSmartCare wants to assure you of our commitment to privacy and security. QSmartCare operates by the following principles: We will not ask for information that personally identifies you (“Personal Information”) while you are simply browsing our Public Site, www.qsmartcare.com. If this should change, we will explain what the information for which we are asking is to be used. If you request to download a software demo from our Public Site, we might ask for personal information. This information will only be used for tracking purposes or to contact you personally. This information will never be shared outside of QSmartCare.

If you are visiting a QSmartCare Secure Site, to which access is limited to our Business Alliance Partners, we may collect the personal information that you specifically and knowingly provide while on the QSmartCare Secure Site. The use of such information will be governed by the specific written contract between you and QSmartCare through which you were granted access to such QSMARTCARE Secure Site.

In addition, on a QSmartCare Secure Site such as our support site, we may place a text file called a “cookie” in the browser files of your computer. The cookie itself does not contain personal information although it will enable QSmartCare to relate your use of the QSmartCare Secure Site to information that you have specifically and knowingly provided to the QSmartCare Secure Site.

If you have any questions about this privacy statement, our information handling practices, or any other aspects of your privacy, please send an email to support@qsmartcare.com. Our mailing address is: support@qsmartcare.com. QSmartCare may periodically update this policy to describe how new Web features may affect our use of your information and to let you know of new controls and features that we may provide you. QSmartCare will NOT apply changes to this policy retroactively to information QSmartCare has previously collected.

API

November - 2021

Table of Contents

Introduction. 2

Requirements. 2

How to use the API. 2

API URL. 2

Software Components & Configuration. 3

Authenticate User 3

Search for Patients. 4

Get Patient CCDA. 9

Get patient CCDA for a limited time range. 14

Get Clinical Sections. 15

Get Clinical sections for a specific time period. 17

Error Codes. 18

Terms of Use. 19

Introduction

This document describes QSmartCare EHR API for patient data access. Its purpose is to serve as an interface to obtain demographic and clinical information for patients registered under the QSmartCare EHR domain. The API returns a JSON object with status and embedded CCDA XML. API examples below show how to access the API

Requirements

1) Registered users can use this API to query the EHR for patient data.

2) User must be an authorized user of the QSmartCare

How to use the API

The API is hosted at https://www.qsmartcare.com/patient-api/controller/patient-service.php and is publicly accessible. Obtain demographic/clinical information from patients registered under the QSMARTCARE EMR domain, third parties should first authenticate using a set of credentials (practiced / username / password) obtained from one of the practices currently using QSMARTCARE EHR.

API URL

URL for accessing the API is

https://www.qsmartcare.com/patient-api/controller/patient-service.php?function=authenticateuser

Software Components & Configuration

Software – Postman

Configuration

a) AccessKeyID

b) SecretAccessKey

Authenticate User

Use your credentials to QSmartCare EHR or QSmartCare Portal to authenticate with the API. API returns a token that will be used for all other API calls.

Example

Enter the below URL

https://www.qsmartcare.com/patient-api/controller/patient-service.php?function=authenticateuser

Graphical user interface, application

Description automatically generated

· Enter the AccessKeyID and SecretAccessKey and click ‘Send’

Graphical user interface, text, application, email

Description automatically generated

· On clicking the Send button Token ID will be generated as displayed in the below screenshot

Graphical user interface, application

Description automatically generated

Note: Store the value TokenID. That TokenID will be used for all further calls to API

Search for Patients

Search for a patient from QSMARTCARE using one or more parameters list below

• Account No

• Date of birth

• First name

• Last name

Examples listed below

Search Using Account No

https://www.qsmartcare.com/patient-api/controller/patient-service.php?function=patientsearch&AccessKeyID=7bfa8af158f7ac83&SecretAccessKey=f3c2ad1b20f9778d19e01c73c5db5e&token=0fe7695d4b93fad219b649a18afd27c8&accountno=9999094

Graphical user interface, application

Description automatically generated

Response

{

"PatientList": [

{

"AccountNo": "9999094",

"FirstName": "Rebecca",

"MiddleName": "Jones",

"LastName": "Larson",

"Gender": "F",

"Dob": "05/01/1970",

"Email": "Rebecca@gmail.com",

"Mobile": "(555) 777-1234",

"Address": "1357, Amber Dr, Beaverton, OR-97006",

"City": "Beaverton",

"State": "Oregon",

"Zipcode": "98746-5655"

}

"Result": "Success: Found 1 patients"

}

Search Using Date of birth

Graphical user interface, text, application, email

Description automatically generated

Response for DOB

{

"PatientList": [

{

"AccountNo": "908105",

"FirstName": "Kay",

"MiddleName": "",

"LastName": "Easley",

"Gender": "M",

"Dob": "05/22/1988",

"Email": "test@gmail.com",

"Mobile": "",

"Address": "",

"City": "",

"State": "",

"Zipcode": ""

}

"Result": "Success: Found 1 patients"

}

Search Using firstname

Response for firstname

4 patients are found that match the first name

{

"PatientList": [

{

"AccountNo": "9704105",

"FirstName": "Doris",

"MiddleName": "",

"LastName": "Alvarez",

"Gender": "F",

"Dob": "02/08/1944",

"Email": "",

"Mobile": "",

"Address": "2849 Lesch Glen Ways",

"City": "Terrenceburgh",

"State": "Indiana",

"Zipcode": "46362"

{

"AccountNo": "203",

"FirstName": "Doris",

"MiddleName": "",

"LastName": "Little",

"Gender": "F",

"Dob": "02/27/2002",

"Email": "",

"Mobile": "",

"Address": "1683 Reichert Club Cove",

"City": "South Newton",

"State": "Washington",

"Zipcode": "99076"

{

"AccountNo": "9704608",

"FirstName": "Doris",

"MiddleName": "",

"LastName": "Wright",

"Gender": "F",

"Dob": "03/19/1976",

"Email": "",

"Mobile": "",

"Address": "3922 Lakin Well Mission",

"City": "Boyerborough",

"State": "Minnesota",

"Zipcode": "55529"

{

"AccountNo": "9772002",

"FirstName": "Doris",

"MiddleName": "",

"LastName": "Williams",

"Gender": "M",

"Dob": "05/25/1956",

"Email": "na@na.com",

"Mobile": "",

"Address": "",

"City": "",

"State": "",

"Zipcode": ""

}

"Result": "Success: Found 4 patients"

Search Using lastname

Graphical user interface, text, application, email

Description automatically generated

Response for lastname

1 patient are found that match the first name

{

"PatientList": [

{

"AccountNo": "9704002",

"FirstName": "Sandra",

"MiddleName": "Jones",

"LastName": "Glazer",

"Gender": "F",

"Dob": "05/01/1970",

"Email": "sandratest@mail.com",

"Mobile": "(555) 777-1234",

"Address": "",

"City": "Beaverton",

"State": "Oregon",

"Zipcode": "97006-"

}

"Result": "Success: Found 1 patients"

Note: To find the correct patient. Use that patient’s account no returned from these calls for remaining API.

Get Patient CCDA

Request the entire CCDA for a patient, using the following command.

https://www.qsmartcare.com/patient-api/controller/patient-service.php?function=patientCCDA&AccessKeyID=7bfa8af158f7ac83&SecretAccessKey=f3c2ad1b20f9778d19e01c73c5db5e&token=0fe7695d4b93fad219b649a18afd27c8&account=9999094

Graphical user interface, text, application, email

Description automatically generated

Response for PatientCCDA

<?xml version="1.0"?>

<?xml-stylesheet type='text/xsl' href='CDA.xsl'?>

<realmCode code="US"/>

<typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>

<templateId root="2.16.840.1.113883.10.20.22.1.1" extension="2015-08-01"/>

<templateId root="2.16.840.1.113883.10.20.22.1.1"/>

<templateId root="2.16.840.1.113883.10.20.22.1.2" extension="2015-08-01"/>

<templateId root="2.16.840.1.113883.10.20.22.1.2"/>

<id root="2.16.840.1.113883.19.5.99999.1" extension="TT660"/>

<code code="34133-9" codeSystem="2.16.840.1.113883.6.1" displayName="Summarization of Episode Note" codeSystemName="LOINC"/>

<title>Patient Chart Summary</title>

<effectiveTime value="20211020131511"/>

<confidentialityCode code="N" codeSystem="2.16.840.1.113883.5.25" displayName="normal" codeSystemName="Confidentiality"/>

<languageCode code="en-US"/>

<setId root="2.16.840.1.113883.19.5.99999.19" extension="sTT660"/>

<versionNumber value="1"/>

<recordTarget>

<patientRole>

<id extension="444222222" root="2.16.840.1.113883.4.1"/>

<addr use="H">

<streetAddressLine>1357, Amber Dr, Beaverton, OR-97006</streetAddressLine>

<city>Beaverton</city>

<state>OR</state>

<postalCode>98746-5655</postalCode>

<country>US</country>

</addr>

<telecom value="tel:+1(555)-777-1234" use="MC"/>

<telecom value="tel:+1(555)-723-1544" use="HP"/>

<patient>

<name use="L">

<given>Rebecca</given>

<given>Jones</given>

<family>Larson</family>

</name>

<name>

<given>Rebecca</given>

<given>Jones</given>

<family>Larson</family>

<given qualifier="BR">Robert</given>

</name>

<administrativeGenderCode code="F" codeSystem="2.16.840.1.113883.5.1" displayName="Female" codeSystemName="AdministrativeGender"/>

<birthTime value="19700501"/>

<maritalStatusCode code="S" codeSystem="2.16.840.1.113883.5.2" displayName="Never Married"/>

<religiousAffiliationCode nullFlavor="NI"/>

<raceCode code="2106-3" codeSystem="2.16.840.1.113883.6.238" displayName="White"/>

<sdtc:raceCode code="2108-9" codeSystem="2.16.840.1.113883.6.238" displayName="European"/>

<ethnicGroupCode code="2186-5" codeSystem="2.16.840.1.113883.6.238" displayName="Not Hispanic or Latino"/>

<languageCommunication>

<languageCode code="en"/>

<modeCode code="ESP" codeSystem="2.16.840.1.113883.5.60" displayName="Expressed spoken" codeSystemName="LanguageAbilityMode"/>

<proficiencyLevelCode code="G" codeSystem="2.16.840.1.113883.5.61" displayName="Good" codeSystemName="LanguageAbilityProficiency"/>

<preferenceInd value="true"/>

</languageCommunication>

</patient>

<providerOrganization>

<id root="2.16.840.1.113883.4.6" extension="219BX"/>

<name>Demo Facility</name>

<telecom value="tel:(234) 234-2423" use="WP"/>

<addr use="WP">

<streetAddressLine>45 Oakland avenue</streetAddressLine>

<city>Alberthashire</city>

<state>AK</state>

<postalCode>12121-2121</postalCode>

<country>US</country>

</addr>

</providerOrganization>

</patientRole>

</recordTarget>

<author>

<time value="202110201315-11"/>

<assignedAuthor>

<id root="2.16.840.1.113883.4.6" extension="5555555555"/>

<code nullFlavor="NI" codeSystem="2.16.840.1.113883.6.101" codeSystemName="Healthcare Provider Taxonomy (HIPAA)" displayName="Adult Medicine"/>

<addr use="HP">

<streetAddressLine>Lake side buliding</streetAddressLine>

<city>Florida City</city>

<state>OR</state>

<postalCode>980-99</postalCode>

<country>US</country>

</addr>

<telecom value="nullFlavor" use="HP"/>

<assignedPerson>

<name>

<given>Sharon Justin</given>

</name>

</assignedPerson>

</assignedAuthor>

</author>

<dataEnterer>

<assignedEntity>

<id root="2.16.840.1.113883.4.6" extension="333777777"/>

<addr use="WP">

<streetAddressLine>Lake side buliding</streetAddressLine>

<city>Florida City</city>

<state>OR</state>

<postalCode>980-99</postalCode>

<country>US</country>

</addr>

<telecom value="nullFlavor" use="WP"/>

<assignedPerson>

<name>

<given>Sharon Justin</given>

</name>

</assignedPerson>

</assignedEntity>

</dataEnterer>

<custodian>

<assignedCustodian>

<representedCustodianOrganization>

<id root="2.16.840.1.113883.4.6" extension="321CX"/>

<name>Demo Facility</name>

<telecom value="tel:(234) 234-2423" use="WP"/>

<addr use="WP">

<streetAddressLine>45 Oakland avenue</streetAddressLine>

<city>Alberthashire</city>

<state>AK</state>

<postalCode>12121-2121</postalCode>

<country>US</country>

</addr>

</representedCustodianOrganization>

</assignedCustodian>

</custodian>

<legalAuthenticator>

<time value="1634735711"/>

<signatureCode code="S"/>

<assignedEntity>

<id root="2.16.840.1.113883.4.6" extension="5555555555"/>

<code nullFlavor="NI" codeSystem="2.16.840.1.113883.6.101" codeSystemName="Healthcare Provider Taxonomy (HIPAA)" displayName="Adult Medicine"/>

<addr use="WP">

<streetAddressLine>1004 Healthcare Drive</streetAddressLine>

<city>Portland</city>

<state>OR</state>

<postalCode>99123</postalCode>

<country>US</country>

</addr>

<telecom value="tel:+1(555)555-1004" use="WP"/>

<assignedPerson>

<name>

<given>Patricia</given>

<family>Primary</family>

<suffix qualifier="AC">M.D.</suffix>

</name>

</assignedPerson>

</assignedEntity>

</legalAuthenticator>

<documentationOf>

<serviceEvent classCode="PCPR">

<effectiveTime>

<low value="19880101000000"/>

<high value="20211020131511"/>

</effectiveTime>

<performer typeCode="PRF">

<originalText>Primary Care Provider</originalText>

</functionCode>

<assignedEntity>

<id root="2.16.840.1.113883.4.6" extension="5555555555"/>

<code nullFlavor="NI" codeSystem="2.16.840.1.113883.6.101" codeSystemName="Healthcare Provider Taxonomy (HIPAA)" displayName="Adult Medicine"/>

<addr>

<streetAddressLine>1004 Healthcare Drive</streetAddressLine>

<city>Portland</city>

<state>OR</state>

<postalCode>99123</postalCode>

<country>US</country>

</addr>

<telecom value="tel:+1(555)555-1004" use="WP"/>

<assignedPerson>

<name>

<given>Patricia</given>

<family>Primary</family>

<suffix qualifier="AC">M.D.</suffix>

</name>

</assignedPerson>

<representedOrganization>

<id root="1.2.16.840.1.113883.4.6" extension="219BX"/>

<name>The DoctorsTogether Physician Group</name>

<telecom value="tel:+1(555)555-5000" use="WP"/>

<addr>

<streetAddressLine>1004 Healthcare Drive</streetAddressLine>

<city>Portland</city>

<state>OR</state>

<postalCode>99123</postalCode>

<country>US</country>

</addr>

</representedOrganization>

</assignedEntity>

</performer>

</serviceEvent>

</documentationOf>

<component>

<structuredBody>

</ClinicalDocument>

Get patient CCDA for a limited time range.

Note: Start and end date are formatted as YYYY-MM-DD.

Response will be the same CCDA as above, except the encounters will be restricted to date of service between 22 June 2015 to 24 June 2015.

Graphical user interface, application

Description automatically generated

Get Clinical Sections

https://mu.qsmartcare.com/patient-api/controller/patient-service.php?function=patientData&AccessKeyID=80b790b6ce24e591&SecretAccessKey=cdb461b1d9d78c3b3e62f6397c0704&token=88b63423152f144f7a71abe9eac1473d&accountno=9120001&sectionName=<sectionName for API>

In the command above, “sectionName for API” can be one of the following.

sectionName value provided to API	Clinical Section returned by API
all	All
demographics	Patient Demographics
careteam	Care Team
allergies	Allergies and Intolerances
assessments	Assessment
goals	Goals
healthconcerns	Health Concerns
immunizations	Immunizations
labtest	Lab Test
medications	Medications
problem	Problem
procedures	Procedures
results	Results
socialhistory	Social History
vitalsigns	Vital Signs
implantabledevice	Implantable Device
reasonforreferral	Reason for Referral
encounters	Encounters
functionalstatus	Functional Status
cognitivestatus	Cognitive Status
planoftreatment	Plan of treatment

Example: If sectionName=allergies, following CCDA will be returned.

https://www.qsmartcare.com/patient-api/controller/patient-service.php?function=patientData&AccessKeyID=7bfa8af158f7ac83&SecretAccessKey=f3c2ad1b20f9778d19e01c73c5db5e&token=0fe7695d4b93fad219b649a18afd27c8&accountno=9999094&sectionName=allergies

Graphical user interface, text, application, email

Description automatically generated

Response as follows

<!—CCDA Header -- >

!-- ********************************** ALLERGIES ********************************** -->

<component>

<section>

<templateId root="2.16.840.1.113883.10.20.22.2.6.1" extension="2015-08-01"/>

<templateId root="2.16.840.1.113883.10.20.22.2.6.1"/>

<code code="48765-2" codeSystem="2.16.840.1.113883.6.1" codeSystemName="LOINC"/>

<title>ALLERGIES AND ADVERSE REACTIONS</title>

<text>

<table border="1" width="100%">

<thead>

<tr>

<th>Substance</th>

<th>Reaction</th>

<th>Severity</th>

<th>Start Date</th>

<th>End Date</th>

<th>Status</th>

</tr>

</thead>

<tbody>

<tr>

<td ID="substance1">Ampicillin</td>

<td ID="reaction1">Hives</td>

<td ID="severity1">Moderate</td>

<td>May 10, 1980</td>

<td>NA</td>

<td>active</td>

</tr>

<tr>

<td ID="substance2">Penicillin G</td>

<td ID="reaction2">Hives</td>

<td ID="severity2">Moderate</td>

<td>May 10, 1980</td>

<td>NA</td>

<td>active</td>

</tr>

< !—CCDA footer -- >

Get Clinical sections for a specific time period.

In order to get records for a specific time period, enter the following parameters as shown in the below screenshot.

Note: Start and end date are formatted as YYYY-MM-DD

Graphical user interface, application

Description automatically generated

Response will be the same section name, clinical data will be restricted to date of service between 22 June 2015 to 24 June 2015.

Public Hyperlink

Copy the Url and paste in new browser and press Ctrl + U

Graphical user interface, text, application, email

Description automatically generated

Error Codes

a) Unauthorized access:

When user is not authorized to view requested data, following error will be generated.

{"Result":"Error: Not authorized"}

b) Unauthenticated access:

If the user credentials are invalid or token has expired, following error will be generated.

{"Result":"Error: User not authenticated"}

Example: Enter wrong SecretAccessKey

c) Patient not found:

If the patient record does not exist for the patient being requested, following error will be generated.

{"Result":"Error: Patient not found"}

d) CCDA Section not found:

If the user calls service patientData with invalid section name, following error will be generated.

{"Result":"Error: CCDA section not found"}

e) No Data Available:

If the user calls service patientData with invalid StartDate and EndDate, following error will be generated.

{"Result":"Error: No data available"}

Terms of Use

1. Proprietary Rights. Copyrights. All content on the Site, including but not limited to design, text, software, technical drawings, configurations, graphics, other files, and their selection and arrangement are either Copyright by QSmartCare, or are the property of QSmartCare affiliates or licensors. All rights reserved.

2. User conduct – General (In using this site you agree)

b) not to disrupt or interfere with any other user's enjoyment of the Site or affiliated or linked Web sites

c) not to upload, post, or otherwise transmit through or on this Site any viruses or other harmful, disruptive, or destructive files

d) not to use or attempt to use another's account, service, or system without authorization from Greenway, or create or use a false identity on this Site

e) not to transmit through or on this Site spam, chain letters, junk mail or any other type of unsolicited mass email to people or entities who have not agreed to be part of such mailings.

f) not to divulge your username and password to others either on or off the Site

g) not to attempt to obtain unauthorized access to the Secure Sites; and

h) not use this Site to seek, provide, or obtain specific medical advice, medical opinion, diagnosis, or treatment as applied to a patient's particular condition or situation.

3. Privacy Policy

4. Customer Secure Site

1. use, copy, sublicense, adapt, and transmit; and

5. Links and Third-Party Content

a. the link is a text-only link containing only the title of the home page of this Site

b. the link "points" only to the home page of the Site and not to deeper pages

c. the link, when activated by a user, displays this home page of the Site full-screen and not within a "frame" on the linked Web site, and

d. the appearance, position, and other aspects of the link does not

1. create the false appearance that an entity or its activities or products are associated with or sponsored by QSmartCare or its affiliates, or

6. Disclaimers

This site and the content available through it are provided on an "as is" and "as available" basis. You expressly agree that use of this site and/or its content is at your

sole risk. To the fullest extent permissible pursuant to applicable law, QSmartCare and its affiliates disclaim all warranties of any kind, whether express or implied, including without limitation any warranty of merchantability, fitness for a particular purpose, or non-infringement. You expressly agree that use of this site, including all content, data, or software distributed by, downloaded, or accessed from or through the site, is at your sole risk. You understand and agree that you will be solely responsible for any damage to your business, your computer system, or loss of data that results from the download of such content, data, and/or software. You acknowledge that QSmartCare does not control information, products, or services offered by third parties through the site. Except as otherwise agreed in writing, QSmartCare and its affiliates assume no responsibility for and make no warranty or representation as to the accuracy, currency, completeness, reliability or usefulness of any advice, opinion, statement, or other content or of any products or services distributed or made available by third parties through the site. QSmartCare does not make any warranty that this site or its content will meet your requirements, or that this site or its content will be uninterrupted, timely, secure, or error free, or that defects, if any, will be corrected. Nor does QSmartCare make any warranty as to the results that may be obtained from use of this site or its content or as to the accuracy, completeness, or reliability of any information obtained through use of this site. QSmartCare assumes no responsibility for any damages suffered by a user, including, but not limited to, loss of data from delays, non-deliveries of content or email, errors, system down time, mis deliveries of content or email, network or system outages, file corruption, or service interruptions caused by the negligence of QSmartCare, its affiliates, its licensors, or a user's own errors and/or omissions. Except as specifically provided herein, QSmartCare disclaims any warranty or representation that confidentiality of information transmitted through the site will be maintained. No advice or information, whether oral or written, obtained by you from QSmartCare or through the site shall create any warranty not expressly stated in writing.

7. Limitation of Liability

8. General

9. Other

Privacy Policy

We at Magilen Enterprises Inc. are committed to maintaining the privacy and security of our customers’ personal information on www.qsmartcare.comm Through this privacy statement, QSmartCare wants to assure you of our commitment to privacy and security. QSmartCare operates by the following principles: We will not ask for information that personally identifies you (“Personal Information”) while you are simply browsing our Public Site, www.qsmartcare.comm. If this should change, we will explain what the information for which we are asking is to be used. If you request to download a software demo from our Public Site, we might ask for personal information. This information will only be used for tracking purposes or to contact you personally. This information will never be shared outside of QSmartCare.