MedicsCloud FHIR API

Version 11.0 | HL7 FHIR Release 4(v4.0.1) | SMART on FHIR | ONC Certified

Compliant with §170.315(g)(10)(viii) and 45 CFR 170.404(a)(2)

Advanced Data Systems Corp (ADSC)

1. Introduction & API Syntax

MedicsCloud Ver 11.0 API program offers a comprehensive set of HL7 FHIR APIs that allow third-party developers to build applications by querying patient medical records from MedicsCloud EHR. The APIs also support the SMART App Launch specification, allowing third-party applications to launch from inside or outside the MedicsCloud EHR user interface.

MedicsCloud EHR meets the ONC Health IT Certification Criteria requirements for Certified Electronic Health Records Technology published by the Office of the National Coordinator (ONC).

FHIR Base URL Structure

GET {FHIRBaseURL}/[ResourceType]

GET {FHIRBaseURL}/[ResourceType]/[id]

GET {FHIRBaseURL}/[ResourceType]?[searchParams]

Production Endpoints

FHIR Base URL: https://fhir-service.medicscloud.com/r6/fhir

FHIR Launch URL: https://fhir-service-launch.medicscloud.com/r6

Sandbox Endpoints

FHIR Base URL: https://fhir.medicscloud.com/r6/fhir

FHIR Launch URL: https://fhir-launch.medicscloud.com/r6

Discovery Endpoint

SMART Configuration: GET https://[FHIRBaseURL]/.well-known/smart-configuration

Returns OAuth authorization endpoint, token endpoint URLs, and supported capabilities.

2. Function Names & FHIR Operations

Only HTTP GET request types are supported while accessing FHIR Resource APIs. The following operations and resources are supported:

Operation	HTTP Method	Description
read	GET	Retrieve a specific resource by its logical ID
search-type	GET	Search resources using supported parameters
$export	GET	Bulk data export for multiple patients (Backend Services)

Supported FHIR Resources

#	Resource	Description
1	Patient	Patient demographics and identifiers
2	AllergyIntolerance	Patient allergy and intolerance records
3	CarePlan	Patient care plans (category: assess-plan)
4	CareTeam	Active care team members for a patient
5	Condition	Problem list, encounter diagnoses, and health concerns
6	Device	Implantable device records (US Core Implantable Device profile)
7	DiagnosticReport	Lab, imaging, and procedure reports
8	DocumentReference	Clinical notes and document references
9	Goal	Patient care goals
10	Immunization	Immunization records
11	MedicationRequest	Medication orders and prescriptions
12	Observation (Smoking Status)	Tobacco smoking status (LOINC: 72166-2)
13	Observation (Vitals)	Vital signs observations
14	Procedure	Clinical procedures performed
15	Encounter	Patient encounter/visit records
16	Organization	Healthcare organization details
17	Practitioner	Clinician/provider information
18	Provenance	Data provenance and audit trail
19	DocumentReference (Clinical Notes)	Clinical notes including progress, consult, H&P, discharge, operative, imaging, and lab reports
20	ServiceRequest	Requests for clinical services such as lab tests, imaging, procedures, or referrals
21	Coverage	Patient insurance and payer coverage details
22	MedicationDispense	Records of medications dispensed to the patient (pharmacy supply events)
23	Specimen	Information about collected samples (blood, urine, tissue) used for testing

3. Parameters & Data Types

Authorization Code Request Parameters

Parameter	Type	Required?	Description
response_type	string	Required	Fixed value: code
client_id	string	Required	The client's registered identifier
redirect_uri	URI	Required	Must match one of the client's pre-registered redirect URIs
scope	string	Required	Space-separated list of requested scopes (see Section 10)
state	string	Required	Opaque value for CSRF protection; minimum 122 bits of entropy
aud	URI	Required	Audience URI - must be the FHIR server base URL; used for audit and future enforcement
launch	string	Conditional	Required for EHR Launch flow; omit for Standalone launch
code_challenge	string	Recommended	PKCE challenge value (S256 method recommended)

Token Request Parameters

Parameter	Type	Required?	Description
grant_type	string	Required	authorization_code or refresh_token
code	string	Required	Authorization code received from the EHR authorization server
redirect_uri	URI	Required	Must exactly match the redirect URI used in the authorization request
client_id	string	Required	Registered client identifier

FHIR Resource Search Parameters by Resource

Resource	Supported Search Parameters
Patient	_id, identifier, name, birthdate + name, gender + name
AllergyIntolerance	patient
CarePlan	patient, category (assess-plan)
CareTeam	patient, status (active)
Condition	patient, category (problem-list-item \| health-concern \| encounter-diagnosis), code
Device	patient
DiagnosticReport	patient, patient + code, patient + category, patient + category + date
DocumentReference	patient, patient + type, patient + category, patient + category + date
Goal	patient
Immunization	patient
MedicationRequest	patient, patient + intent, patient + status + intent
Observation (Smoking)	patient, code (72166-2)
Observation (Vitals)	patient + code, patient + category + date
Procedure	patient, patient + date
Encounter	id (direct read)
Organization	id (direct read)
Practitioner	id (direct read)
Provenance	id (direct read)
ServiceRequest	id (direct read)
Coverage	id (direct read)
MedicationDispense	id (direct read)
Specimen	id (direct read)

4. Return Variables & Structures

Access Token Response

{

"need_patient_banner": true,

"smart_style_url": "https://fhir-launch.medicscloud.com/r6/smart_style_url.json",

"patient": "example", // string — FHIR Patient ID

"token_type": "bearer", // string — always "bearer"

"scope": "launch/patient openid fhirUser offline_access ...",

"client_id": "fhirpatient-full", // string

"expires_in": 3600, // integer — seconds until expiry

"id_token": "TOKEN", // string — OIDC identity token

"access_token": "ACCESS_TOKEN", // string — JWT Bearer token

"refresh_token": "REFRESH_TOKEN", // string — opaque refresh token

"encounter": "example", // string — Encounter context ID

"user": "example" // string — authenticated user

}

FHIR Bundle Response (search results)

{

"resourceType": "Bundle",

"id": "bundle-uuid", // string

"meta": { "lastUpdated": "dateTime" },

"type": "searchset", // string

"total": 10, // integer — total matching resources

"link": [{ "relation": "self", "url": "..." }],

"entry": [{ "fullUrl": "...", "resource": { ... }, "search": { "mode": "match" } }]

}

Authorization Code Response (Redirect)

Location: https://app/after-auth?code={authorization_code}&state={state_value}

Tokens issued after code exchange:

1. ID Token — OIDC identity token

2. Access Token — JWT Bearer token (expires_in: 3600)

3. Refresh Token — opaque, used to obtain new access token

5. Exceptions & Error Handling

HTTP Status	Code	Meaning	Recommended Action
200	OK	Request succeeded	Process the returned resource or Bundle
400	Bad Request	Malformed request or missing required parameter	Check request syntax and required parameters
401	Unauthorized	Missing, invalid, or expired access token	Re-authenticate or use refresh token to obtain a new access token
500	Internal Server Error	Unexpected server-side error	Retry the request; contact softwaresupport@adsc.com if issue persists

All error responses are returned as JSON objects with an HTTP status code. Example error response:

{ "error": "invalid_token", "error_description": "Access token is expired or invalid." }

6. Mandatory Software Components

FHIR Version: HL7 FHIR Release 4(v4.0.1)

Implementation Guide: SMART on FHIR US Core 6.1.0 / USCDI v3

Authorization Framework: SMART App Launch 2.0.0

Bulk Data: HL7 Bulk Data v1.0.1

Transport Security: TLS 1.2 or higher (required in all development languages used)

Supported Languages: Any modern language supporting REST-based applications with TLS 1.2+, including Microsoft .NET 4.7+, Java/Kotlin, Python, etc.

Content Type: application/json (FHIR JSON format)

HTTP Methods: GET only for FHIR Resource API access

7. Mandatory Software Configurations

Client Registration: Required before accessing the API. Apps must be registered via email to softwaresupport@adsc.com (see Section 8).

SMART Configuration Discovery: Apps must retrieve /.well-known/smart-configuration to discover authorization and token endpoint URLs before initiating the OAuth flow.

State Parameter: The state parameter in authorization requests must contain at least 122 bits of entropy (e.g., a properly configured random UUID) to prevent CSRF and session fixation attacks.

Redirect URI: Must be pre-registered; must match exactly in all authorization and token requests.

Token Expiry: Access tokens expire in 3600 seconds. Applications must handle token expiry by using the refresh token to obtain a new access token.

Scope Declaration: Applications must declare all required scopes at registration and during the authorization request.

Data Access: Read-only; only FHIR APIs listed within the USCDI v3 core data set are supported. Only HTTP GET is supported.

8. Authorization Server Registration Requirements

Before a SMART app can run against MedicsCloud EHR, the app must be registered with the EHR's authorization service using OAuth 2.0 Client Registration. To request registration, send an email to:

To: softwaresupport@adsc.com

Subject: FHIR API Access Request

Include the following details:

1. Email Address

2. First Name

3. Last Name

4. Job Title

5. Application Name

6. Application Details

7. Company Name

Upon approval, the EHR admin creates the application and communicates a client_id to the applicant. The following attributes are required for registration:

Attribute	Description
Email Address	Primary contact email for the developer/organization
First & Last Name	Developer or authorized representative name
Job Title	Role of the registrant
Application Name	Name of the SMART app to be registered
Application Details	Description of the application's purpose and data needs
Company Name	Legal name of the organization requesting access

9. US Core IG Choices & References Supported [g10 CCG]

This module supports SMART on FHIR US Core 6.1.0 / USCDI v3. The following US Core profiles are implemented. FHIR APIs listed within the USCDI v3 core data set are supported. Only read operations are supported.

Resource	US Core Profile	Search Parameters Supported
Patient	US Core Patient Profile	_id, identifier, name, birthdate+name, gender+name
AllergyIntolerance	US Core AllergyIntolerance Profile	patient
CarePlan	US Core CarePlan Profile	patient, category (assess-plan)
CareTeam	US Core CareTeam Profile	patient, status
Condition	US Core Condition Profile	patient, category, code
Device	US Core Implantable Device Profile	patient
DiagnosticReport	US Core DiagnosticReport (Lab & Note)	patient, code, category, date
DocumentReference	US Core DocumentReference Profile	patient, type, category, date
Goal	US Core Goal Profile	patient
Immunization	US Core Immunization Profile	patient
MedicationRequest	US Core MedicationRequest Profile	patient, intent, status
Observation	US Core Smoking Status & Vital Signs	patient, code, category, date
Procedure	US Core Procedure Profile	patient, date
Encounter	US Core Encounter Profile	id (direct read)
Organization	US Core Organization Profile	id (direct read)
Practitioner	US Core Practitioner Profile	id (direct read)
Provenance	US Core Provenance Profile	id (direct read)
ServiceRequest	US Core Practitioner Profile v6.1.0	id (direct read)
Coverage	US Core Provenance Profile v6.1.0	id (direct read)
MedicationDispense	US Core Practitioner Profile v6.1.0	id (direct read)
Specimen	US Core Provenance Profile v6.1.0	id (direct read)

Medication choice references: medicationCodeableConcept (e.g., RxNorm coded medications) is supported in MedicationRequest resources.

Patient extensions: Includes us-core-race, us-core-ethnicity, us-core-birthsex, us-core-sex, us-core-genderIdentity, patient-birthPlace, and patient-mothersMaidenName extensions.

Provenance agents: Provenance resources include both author and transmitter agent types with references to Practitioner and Organization.

10. Supported Scopes [g10 CCG]

The following scopes are supported per SMART App Launch 2.0.0 Applications must request only the scopes necessary for their intended function.

Scope	Description
patient/*.read	Permission to read and search any resource for the current patient
user/*.read	Permission to read all resources that the current user can access
openid	Permission to retrieve information about the current logged-in user
fhirUser	Returns the FHIR resource representing the current user
launch	Permission to obtain launch context when app is launched from an EHR
launch/patient	When launching outside the EHR, request patient selection at launch time
offline_access	Request a refresh token usable after the end-user is no longer online
patient/Patient.read	Read Patient resources for the current patient
patient/AllergyIntolerance.read	Read AllergyIntolerance resources
patient/CarePlan.read	Read CarePlan resources
patient/CareTeam.read	Read CareTeam resources
patient/Condition.read	Read Condition resources
patient/Device.read	Read Device (implantable) resources
patient/DiagnosticReport.read	Read DiagnosticReport resources
patient/DocumentReference.read	Read DocumentReference (clinical notes) resources
patient/Encounter.read	Read Encounter resources
patient/Goal.read	Read Goal resources
patient/Immunization.read	Read Immunization resources
patient/Location.read	Read Location resources
patient/Medication.read	Read Medication resources
patient/MedicationRequest.read	Read MedicationRequest resources
patient/Observation.read	Read Observation resources (vitals, smoking status, labs)
patient/Organization.read	Read Organization resources
patient/Practitioner.read	Read Practitioner resources
patient/Procedure.read	Read Procedure resources
patient/Provenance.read	Read Provenance resources
patient/PractitionerRole.read	Read PractitionerRole resources
patient/QuestionnaireResponse.read	Read QuestionnaireResponse resources
patient/RelatedPerson.read	Read RelatedPerson resources
patient/ServiceRequest.read	Read ServiceRequest resources
patient/Specimen.read	Read Specimen resources
patient/Coverage.read	Read Coverage resources

user/AllergyIntolerance.read	Read AllergyIntolerance resources
user/CarePlan.read	Read CarePlan resources
user/CareTeam.read	Read CareTeam resources
user/Condition.read	Read Condition resources
user/Device.read	Read Device (implantable) resources
user/DiagnosticReport.read	Read DiagnosticReport resources
user/DocumentReference.read	Read DocumentReference (clinical notes) resources
user/Encounter.read	Read Encounter resources
user/Goal.read	Read Goal resources
user/Immunization.read	Read Immunization resources
user/Location.read	Read Location resources

user/Medication.read	Read Medication resources
user/MedicationRequest.read	Read MedicationRequest resources
user/Observation.read	Read Observation resources (vitals, smoking status, labs)
user/Organization.read	Read Organization resources
user/Practitioner.read	Read Practitioner resources
user/Procedure.read	Read Procedure resources
user/Provenance.read	Read Provenance resources
user/PractitionerRole.read	Read PractitionerRole resources
user/QuestionnaireResponse.read	Read QuestionnaireResponse resources
user/RelatedPerson.read	Read RelatedPerson resources
user/ServiceRequest.read	Read ServiceRequest resources
user/Specimen.read	Read Specimen resources
user/Coverage.read	Read Coverage resources

Note: Write scopes are not supported. All access is read-only.

11. TLS Enforcement [g10 CCG]

Minimum version: TLS 1.2. All development languages and frameworks used must support building REST-based applications with TLS 1.2 or higher.

Recommended: TLS 1.3 where supported by the client environment.

Scope of enforcement: TLS is required on all endpoints: FHIR Base URL, FHIR Launch URL, Authorization endpoint, Token endpoint, and .well-known/smart-configuration.

Implementation: Supported languages include .NET 4.7+ (which defaults to TLS 1.2+), Java/Kotlin (via JSSE with TLS 1.2+ configured), and Python (via ssl module with PROTOCOL_TLS_CLIENT). All must negotiate TLS 1.2 at minimum.

Certificate: All production endpoints use certificates signed by a publicly trusted Certificate Authority (CA).

12. Refresh Token Issuance — Native Applications [g10 CCG]

MedicsCloud supports the secure issuance of initial refresh tokens to native applications using the OAuth 2.0 Authorization Code flow with SMART App Launch 2.0.0.

Method: SMART App Launch 2.0.0 Authorization Code flow. A refresh token is issued when the offline_access scope is requested and granted during the authorization flow.

Native app support: Applications may use loopback redirect URIs or custom URI schemes (pre-registered). The application must be registered in advance via softwaresupport@adsc.com.

Refresh token use: The refresh token can be used to obtain a new access token and refresh token after the current access token expires, even when the end-user is no longer online.

SMART App Launch Steps

Step	Action
1	Client Application Registration (via softwaresupport@adsc.com) including redirect URI and scopes
2	Retrieve SMART configuration from /.well-known/smart-configuration endpoint
3	Initiate Authorization Request to /connect/authorize endpoint
4	User authenticates and grants consent
5	Authorization Server returns Authorization Code to client redirect URI
6	Client exchanges Authorization Code for Access Token at /connect/token endpoint

7	Client accesses FHIR API using Access Token in Authorization header (Bearer token)

8	Client uses Refresh Token (if granted) to obtain new Access Token when expired

9	System enforces scope validation (patient/* or user/*) and aud validation for each request

10	Use Launch scope for Practitioner and Launch/patient for Patient to get access

Obtain Access Token — Token Endpoint

POST https://[FHIRLaunchURL]/api/auth/token

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

grant_type=authorization_code

&code={authorization_code}

&redirect_uri={registered_redirect_uri}

&client_id={client_id}

Refresh Token Request

POST https://[FHIRLaunchURL]/api/auth/token

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

grant_type=refresh_token

&refresh_token={opaque_refresh_token}

&client_id={client_id}

13. Additional Supported Data [g10 CCG]

Beyond the required USCDI v3 core data elements, MedicsCloud additionally supports the following in the context of the adopted standards and implementation specifications:

SMART App Types: Three SMART application types are supported: (1) Patient Standalone App with Full or Limited Access, (2) Provider EHR Launch App, and (3) Smart Backend Services App for server-to-server multi-patient bulk data export.

Patient extensions: us-core-race, us-core-ethnicity, us-core-birthsex, us-core-sex (SNOMED), us-core-genderIdentity, patient-mothersMaidenName, patient-birthPlace, and geolocation extensions on Address elements.

Provenance: Provenance resources are available for clinical resources including DiagnosticReport, Patient, and Encounter. Agent types include both author and transmitter with references to Practitioner and Organization.

Bulk data export: $export operation supported via Smart Backend Services App for multi-patient group-level data export.

Clinical Notes: DocumentReference supports multiple note types: Progress Note (11506-3), Consultation Note (11488-4), Discharge Summary (18842-5), Procedure Note (34117-2), Operative Note (28570-0), History and Physical (18748-4), Imaging Report (11502-2), and Laboratory Report (11526-1).

DiagnosticReport categories: Supports Laboratory (LAB / LP29708-2), Imaging (LP7839-6), and Procedure (LP29684-5) categories.

OIDC support: ID tokens are issued to support OpenID Connect identity assertions for authenticated users.

14. API Terms & Conditions [45 CFR 170.404(a)(2)]

1. Terms Acceptance and Representation

a. Accepting the Terms. These Terms of Use govern your access to and use of the Certified MedicsCloud EHR ONC Health IT API, documentation, and services. By accessing or using the Certified MedicsCloud EHR APIs, you agree to be bound by these Terms. You represent and warrant that you are at least 18 years of age and possess the legal right and ability to agree to these Terms.

b. Entity Representation. If using the API on behalf of a legal entity, you represent that you have proper authority to act on behalf of and bind the entity to these Terms.

2. Representations and Responsibilities

a. Compliance. You agree to comply at all times with all applicable laws, rules, and regulations. MedicsCloud EHR reserves the right to monitor and periodically audit your use of the APIs.

b. Virus Warranty. You warrant that your applications will not contain any viruses, malicious code, or techniques designed to threaten, infect, damage, or disable the MedicsCloud EHR APIs or any connected systems.

3. General Terms

a. Changes. MedicsCloud EHR may, in its sole discretion, make changes to the API without notice.

b. Global Availability. The APIs are intended for use within the United States. Access from outside the US is at the user's own risk and initiative.

c. Intellectual Property. The APIs and all MedicsCloud EHR software and services are proprietary. No ownership rights are transferred. No rights or licenses are granted other than those expressly stated in these Terms.

d. Waiver, Release, and Limitation of Liability. MedicsCloud EHR shall not be liable for any direct, indirect, punitive, incidental, special, or consequential damages arising from use of the APIs. ALL APIs ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MEDICSCLOUD EHR DISCLAIMS ALL WARRANTIES INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

e. Indemnification. You agree to indemnify, defend, and hold harmless MedicsCloud EHR, its officers, directors, employees, agents, and suppliers from and against all claims, liabilities, losses, expenses, damages, and costs resulting from any violation of these Terms or your use of the APIs.

f. Term and Termination. Either party may terminate API access at any time with or without cause upon notice. MedicsCloud EHR reserves the right to disable access if an application poses security, privacy, or patient safety risks.

g. Governing Law. These Terms are governed by US federal law or the laws of the State of New Jersey.

h. Application Developer Affirmations. Developer affirmations to Certified API Developers regarding the ability of their applications to secure a refresh token, a client secret, or both, must be treated in good faith.

Equal Access: API access is provided on equal, non-discriminatory terms per 45 CFR 170.404. No fees are charged for access to or use of this API for the purposes of accessing electronic health information.

Contact: For API access requests or support: softwaresupport@adsc.com

For full API Documentation: https://fhir.medicscloud.com/docs/MedicsCloud-FHIR-API-full.htm