RAPID  v9.0 CCDS API v1.0

Introduction

Purpose

To allow developers of other health IT applications (API Client) to make read-only data requests for patient health information that is part of the Common Clinical Data Set (CCDS) according to the requirements of 2015 CEHRT Regulations 170.315(g)(7), 170.315(g)(8), and 170.315(g)(9) and in accordance with RAPID  API Terms of Use.

Implementation Requirements

The following software components and configurations must be in place in order to be able to successfully interact with the RAPID  CCDS API and process its responses:

• RAPID  user with "Administrator" access must configure within RAPID  at least one user with "API" access and share this user's Username and Password with the API Client, along with their practice's RAPID  root URL
• API Client must be able to make HTTPS requests
• API Client must be able to authenticate to RAPID  CCDS API using Basic Authentication over HTTPS with the above-mentioned Username and Password
• API Client must be able to parse JSON responses
• API Client must be able to read ZIP files in order to process the response from the All Data Request

API Syntax

RAPID  CCDS API is based on HTTP request-response model. API Clint makes a GET request to one of the three URLs representing the three API functions that are currently available (I. Patient Selection, II. Data Category Request, and III. All Data Request). Required and optional parameters are appended to the URL in the form of a URL-encoded query string. The response consists of a numeric status code, a set of headers, and a body. If the request is successful, the status code is 200, and the body of the response is the requested data in the format described by the Content-Type header. If the request fails due to the values of supplied parameters, the status code is 400, and the body of the response is a human-readable error message. In all other cases the value of the status code and the contents of the body are defined by the HTTP spec.

I. Patient Selection

Purpose

To respond to requests containing sufficient information to uniquely identify a patient and return a Patient ID that can be used by an application to subsequently execute requests for that patient's data.

Function Name

/application_access/v1/patient_selection

Required Parameters

One or more of the following:

• last_name (string)
• first_name (string)
• middle_name (string)
• sex (string formatted as "M", "F", or "UNK" for "Unknown")
• dob (string formatted as "yyyy-mm-dd")
• email (string)
• home_phone (string formatted as numbers only)
• cell_phone (string formatted as numbers only)

Optional Parameters

See Required Parameters above. Each parameter can be considered optional as long as at least one of the parameters is present in the request.

Return Value

If the request is successful, the body of the response is the Patient ID (integer).

Example Request:

        https://localhost:3000/application_access/v1/patient_selection?last_name=newman&dob=1970-05-01

Response Status Code:

        200

Content-Type:

        text/plain

Response Body:

        7856

Exceptions and Exception Handling

The request may fail to uniquely identify a specific patient, either because none of the patients matched the query or because more than one patient matched the query. In this case the status code is 400, and the body of the response is a human-readable error message to that effect.

Example Request:

        https://localhost:3000/application_access/v1/patient_selection?last_name=smith

Response Status Code:

        400

Response Body:

        query did not uniquely identify a specific patient

Test Client

API URL:
Last Name:
First Name:
Middle Name:
Sex:
Date of Birth:
Email:
Home Phone:
Cell Phone:

II. Data Category Request

Purpose

To respond to requests for patient data using a Patient ID for each of the individual categories listed in the Common Clinical Data Set (CCDS) and return the full set of data for that category, according to the required data standards in a computable format. To respond to requests for patient data associated with a specific date as well as with a specific date range.

Function Name

/application_access/v1/data_request_category

Required Parameters

• patient_id (integer)

Optional Parameters

• start_date (string formatted as "yyyy-mm-dd")
• end_date (string formatted as "yyyy-mm-dd")
• category (string, possible values listed below)
• demographics
• smoking_status
• problems
• medications
• allergies
• lab_tests
• lab_results
• vital_signs
• procedures
• care_team_members
• immunizations
• implantable_devices
• assessments
• plan_of_treatment
• goals
• health_concerns

Return Value

If the request is successful, the body of the response is a JSON object with keys corresponding to the requested categories and values representing all available data for the requested category in the requested date range. The date range is inclusive. If start_date is not provided, "since beginning of time" is assumed. If end_date is not provided, "present day" is assumed. There are the following exceptions to this general rule:

• For demographics, the date range is ignored completely, and the values always represent the most up-to-date information about the patient.
• For smoking_status, problems, medications, allergies, immunizations, implantable_devices, and health_concerns, the start_date is ignored, and the values represent the most up-to-date information in patient record for the requested category "as of" the end_date.

Example Request:

        https://localhost:3000/application_access/v1/data_request_category?patient_id=7856&start_date=2015-06-22&end_date=2015-07-22&category=smoking_status&category=lab_tests

Response Status Code:

        200

Content-Type:

        application/json

Response Body:

        {

          "smoking_status": {

            "code": "449868002",

            "code_system_oid": "2.16.840.1.113883.6.96",

            "code_system_name": "SNOMED-CT",

            "text": "Current every day smoker",

            "start_date": "2015",

            "end_date": null

          },

          "lab_tests": [

            {

              "code": "24357-6",

              "code_system_oid": "2.16.840.1.113883.6.1",

              "code_system_name": "LOINC",

              "text": "Urinanalysis macro (dipstick) panel",

              "date": "2015-06-22"

            },

            {

              "code": "24357-6",

              "code_system_oid": "2.16.840.1.113883.6.1",

              "code_system_name": "LOINC",

              "text": "Urinanalysis macro (dipstick) panel",

              "date": "2015-06-29"

            }

          ]

        }

Exceptions and Exception Handling

The request may fail if the Patient ID does not correspond to any patient in the database. In this case the status code is 400, and the body of the response is a human-readable error message to that effect.

Example Request:

        https://localhost:3000/application_access/v1/data_request_category?patient_id=0

Response Status Code:

        400

Response Body:

        patient 0 does not exist

Note: Official CCDS Reference Categories and the corresponding RAPID  CCDS API Categories ("API response groupings")

Official CCDS Reference Category	RAPID  CCDS API Category
(1) Patient Name	demographics
(2) Sex	demographics
(3) Date of Birth	demographics
(4) Race	demographics
(5) Ethnicity	demographics
(6) Preferred Language	demographics
(7) Smoking Status	smoking_status
(8) Problems	problems
(9) Medications	medications
(10) Medication Allergies	allergies
(11) Laboratory Tests	lab_tests
(12) Laboratory Values(s)/Result(s)	lab_results
(13) Vital Signs	vital_signs
(15) Procedures	procedures
(16) Care Team Member(s)	care_team_members
(17) Immunizations	immunizations
(18) Unique Device Identifier(s) for a Patient's Implantable Device(s)	implantable_devices
(19) Assessment and Plan of Treatment	assessments
(19) Assessment and Plan of Treatment	plan_of_treatment
(20) Goals	goals
(21) Health Concerns	health_concerns

Test Client

API URL:
Patient ID:
Start Date:
End Date:
	Demographics
	Smoking status
	Problems
	Medications
	Allergies
	Lab tests
	Lab results
	Vital signs
	Procedures
	Care team members
	Immunizations
	Implantable devices
	Assessments
	Plan of treatment
	Goals
	Health concerns

III. All Data Request

Purpose

To respond to requests for patient data using a Patient ID for all of the data categories specified in the Common Clinical Data Set (CCDS) at one time in a summary record formatted according to the Consolidated CDA Release 2.1 Continuity of Care ument (CCD) template. To respond to requests for patient data associated with a specific date as well as with a specific date range.

Function Name

/application_access/v1/data_request_all

Required Parameters

• patient_id (integer)

Optional Parameters

• start_date (string formatted as "yyyy-mm-dd")
• end_date (string formatted as "yyyy-mm-dd")

Return Value

If the request is successful, the body of the response is a zip file containing one ument per encounter date of service in the requested date range. The date range is inclusive. If start_date is not provided, "since beginning of time" is assumed. If end_date is not provided, "present day" is assumed.

Example Request:

        https://localhost:3000/application_access/v1/data_request_all?patient_id=7856

Response Status Code:

        200

Content-Type:

        application/zip

Response Body:

        <binary data>

Exceptions and Exception Handling

The request may fail if the Patient ID does not correspond to any patient in the database. In this case the status code is 400, and the body of the response is a human-readable error message to that effect.

Example Request:

        https://localhost:3000/application_access/v1/data_request_all?patient_id=0

Response Status Code:

        400

Response Body:

        patient 0 does not exist

Test Client

API URL:
Patient ID:
Start Date:
End Date: