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.
All patient data access requests are formatted in the following format:
GET [base]/[resource-specific parameters]
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:
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:
EndPoint | URL |
---|---|
Authorization | https://[baseOAuthURL]/authz |
Token | https://[baseOAuthURL]/token |
Registration | https://[baseOAuthURL]/register |
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.
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:
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
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
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.
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 |
HTTP Response (Code) | Meaning |
---|---|
400 = Bad Request | Request cannot be processed due to: temporarily unavailable, unsupported resource type, system error API response will contain OperationOutcome Resource with info regarding issue contained in the OperationOutcome.issue element |
400 = Unauthorized | Access token used in the request is invalid, expired, or user has not been authorized to access the requested resource |