API Developer Documentation

MedMagic 2.2

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


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:

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.

API Details

  1. Query Specific Data Category Resource
  2. 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

  3. Patient Selection
  4. 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:


    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:


  5. Query for Specific Data Category

  6. 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:




    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:


  7. Query All Data as a CCDA Document

  8. 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:


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

  9. Query for a Specific Date or Date Range

  10. 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


Error Handling

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

                                                 Terms of Use