API Developer Documentation

General Information

This document provides instructions for a third-party developer to use MedMagic’s REST API to securely access patient health data from MedMagic 2.2.

Application Access Requests

All patient data access requests are formatted in the following format:

GET [base]/[resource-specific parameters]

Application Configuration

Clients must access the server through an HTTPS connection; the connection must be SSL/TLS (TLS 1.0 or higher). Before making any API requests, the client software must obtain an Access Token from the associated Authorized server.

Third-party developers (patients included) must have software configured to:

1. Support the appropriate OAuth 2.0 parameters (detailed information in RFC 6749):
1. Client ID
2. Client Secret
3. Redirect URI
2. Make HTTPS REST requests in compliance with the FHIR specification

Authentication:

Obtaining an Access Token:

The [base] URL, unique to every healthcare organization, will need to be obtained from the data holder to access the Authorization Server. The following endpoint URLs are required:

The end user will first be directed to the authorization endpoint where the user will be presented with a login screen to enter credentials for the healthcare organization they are trying to access. Authentication is performed using a username and password; credentials will need to be obtained by contacting the health care facility directly. If the credentials correctly verify the end user, an authorization code is returned to the client. The client application can then use this code to obtain an access token through the token endpoint.

API Details

1. Query Specific Data Category Resource

Client software needs to be able to make HTTPS RESTful requests in accordance with the FHIR specification and consuming the following FHIR resources to support the common clinical data set:




Category	Resource	Data Element	Data Type	Mandatory
Patient Name	Patient	Patient.name	String	Yes
Patient ID	Patient	Patient.id	String	Yes
Sex	Patient	Patient.gender	String	Yes
Date of Birth	Patient	Patient.birthDate	Date	Yes
Race	Patient	Patient.extension	String	Yes
Ethnicity	Patient	Patient.extension	String	Yes
Preferred Language	Patient	Patient.communication	String	Yes
Smoking Status	Observation		String	Yes
Problems	Condition		String	Yes
Medications	MedicationStatement		String	Yes
Medication Allergies	AllergyIntolerance		String	Yes
Laboratory Tests	Observation	Observation.code	String	Yes
Laboratory Values Results	Observation	Observation.value[x]	String	Yes
Vital Signs	Observation		String	Yes
Procedures	Procedure		String	Yes
Care Team Members	CareTeam		String	Yes
Immunizations	Immunization		String	Yes
Unique Device Identifiers	Device	Device.udiCarrier	String	Yes
Assessment and Plan	CarePlan		String	Yes
Goals	Goal		String	Yes
Health Concerns	Condition		String	Yes




For more information, please view the URLs listed in the below table:




CCDS Category	Data Element/Resource	URL
Patient Name	Patient.name	http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.name
Sex	Patient.gender	http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.gender
Date of Birth	Patient.birthDate	http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.birthDate
Race	Patient.extension	http://hl7.org/fhir/2016Sep/extension-us-core-race.html
Ethnicity	Patient.extension	http://hl7.org/fhir/2016Sep/extension-us-core-ethnicity.html
Preferred Language	Patient.communication	http://hl7.org/fhir/2016Sep/patient-definitions.html#Patient.communication
Smoking Status	Observation	http://hl7.org/fhir/2016Sep/observation.html
Problems	Condition	http://hl7.org/fhir/2016Sep/condition.html
Medications	MedicationStatement	http://hl7.org/fhir/2016Sep/medicationstatement.html
Medication Allergies	AllergyIntolerance	http://hl7.org/fhir/2016Sep/allergyintolerance.html
Laboratory Tests	Observation.code	http://hl7.org/fhir/2016Sep/observation-definitions.html#Observation.code
Laboratory Values Results	Observation.value[x]	http://hl7.org/fhir/2016Sep/observation-definitions.html#Observation.value_x
Vital Signs	Observation	http://hl7.org/fhir/2016Sep/observation.html
Procedures	Procedure	http://hl7.org/fhir/2016Sep/procedure.html
Care Team Members	CareTeam	http://hl7.org/fhir/2016Sep/careteam.html
Immunizations	Immunization	http://hl7.org/fhir/2016Sep/immunization.html
Unique Device Identifiers	Device.udiCarrier	http://hl7.org/fhir/2016Sep/device-definitions.html#Device.udiCarrier
Assessment and Plan	CarePlan	http://hl7.org/fhir/2016Sep/careplan.html
Goals	Goal	http://hl7.org/fhir/2016Sep/goal.html
Health Concerns	Condition	http://hl7.org/fhir/2016Sep/condition.html



2. Patient Selection

When searching for patients, a bundle of Patient resources should be requested matching the suitable search criteria.

An optional search parameter can be applied to the Patient resource using the below parameters:




Resource	Parameter
Patient.name.family	family
Patient.birthdate	birthdate




As an example, a user authorized to view a specific bundle of Patient resources, where the patient’s last name is “Doe” and the patient was born on “July 4th, 1989” could format a request like the below:

https://[baseURL]/Patient?family=Doe&birthdate=1989-07-04

A bundle of patients, or none, matching the search criteria would be returned; only patients that the user is authorized to view will be included in these results.

Every patient also has a unique patient ID found in the Patient.id element of the Patient Resource. If the above patient has a unique id of: 1234, the bundle of Patient resources can also be retrieved formatted in a request like the below:

https://[baseURL]/Patient/1234



3. Query for Specific Data Category



When retrieving a specific data category, the patient ID should be specified in the request. For example, to retrieve a bundle of Immunization resources that contain an immunization history of Patient 1234, the retrieved format could be like the requests below:

https://[baseURL]/Patient/1234/Immunization

                               OR

https://[baseURL]/Immunization?patient=1234

For CCDS categories that share the same Resource, the following search terms can be used to isolate results for a single CCDS category:



CCDS Category	Search Term
Smoking Status	code=http://loinc.org|72166-2
Problems	category=http://argonaut.hl7.org/extension-codes|problem
Laboratory Tests & Laboratory Values/Results	category=http://hl7.org/fhir/observation-category|laboratory
Vital Signs	category=http://hl7.org/fhir/observation-category|vital-signs
Health Concerns	category=http://argonaut.hl7.org/extension-codes|health-concern





As an example, to retrieve the Smoking Status for Patient 1234, the request could be formatted such as:

https://[baseURL]/Patient/1234/Observation?code=http://lloinc.org|72166-2




4. Query All Data as a CCDA Document



CCDA documents are considered “Summary of Episode” Notes within DocumentReference resources. They have a LOINC code of 34133-9. An example format of retrieving a CCDA document for all dates of Patient 1234, would be:


https://[baseURL]/DocumentReference?patient=1234&type=http://loinc.org|34133-9

The CCDA XML data can be found in the DocumentReference.content.attachment data element of the returned Document Reference resource.



5. Query for a Specific Date or Date Range



CCDS data categories/CCDA documents returned by the API can be limited by date; Either a specific date or a date range would need to be indicated. These dates can be included as search parameters defined here:http://hl7.org/fhir/2016Sep/http.html#search; specifying date or date range is optional.


The table below lists the supported search parameters for this:





AllergyIntolerance.reaction.onset	onset
CarePlan.period	date
CareTeam.period	date
Condition.onset	onset
Goal.target	targetdate
Immunization.date	date
MedicationStatement.effective	effective
Observation.effective	date
Procedure.performed	date
DocumentReference.period	period

Exceptions

Error Handling