Overview

This document contains information on the APIs available to retrieve the EHR/MDS data. It is categorized into several functional areas along with Webhook implementation information.

Authorization

This API requires a bearer token for authorization generating using Client Credentials flow . Ensure the generated token has necessary scopes to access the endpoint (scope = ehr for EHR-MDS endpoints).

Sample API request to obtain a token:

curl -X POST "https://api.auth.myzpax.com/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID&grant_type=client_credentials&scope=ehr&client_secret=YOUR_CLIENT_SECRET"

Ensure you include the token in the authorization header in each subsequent API request. The format for the header would need to be:

Authorization: Bearer <your-token>

Important Parameters

The following table below details the default API behavior:

Configuration Setting	Value
Default page size	`10`
Maximum page size	`50`
Access Token Timeout	20 minutes

List of APIs

The following contains the list of APIs that are available client developers.

ADT Records

API	Data	Endpoint
ADT Records	Returns Admission, Discharge, and Transfer (ADT) records for a patient within a facility under a given organization, with the organization code, and `ccn` (CMS Certification Number) and source patient identifier passed in the request, provided the client identified via the token has access to the facility. This endpoint allows optional filtering by effective date and record type to refine the results.	GET /api/v1/adtrecord/{org_code}/ {ccn}/list Get ADT Record List
ADT Event Summaries	Retrieves a summary of ADT (Admission, Discharge, Transfer) events for a specified organization and facility, with the organization code, and `ccn` (CMS Certification Number) passed in the request, provided the client identified via the token has access to the facility. This endpoint allows optional filtering by patient, event type, and date range to refine the event summary results.	GET /api/v1/adtrecords/{org_code}/ {ccn}/event-summary Get ADT Event Summaries
ADT Event Summary	Retrieves a summary of ADT (Admission, Discharge, Transfer) event for a specified event., with the event identifier passed in the request, provided the client identified via the token has access to the facility. This endpoint returns high-level event details, including patient, facility, event type, and event date.	GET api/v1/adtrecord/event-summaries/{event-id} Get ADT Event Summary

✏️
Only the event_ID = 11111111-1111-1111-1111-111111111111 will return a valid response for the ADT Event Summary endpoint, in the testing environment (myzPAX sandbox) associated with the API reference.

ℹ️
ADT Summary Webhook Process
The ADT Summary Job is a scheduled process that transmits summarized ADT (Admission, Discharge, Transfer) event data to each client’s designated webhook endpoint at the 30th minute of every hour.
This ensures that clients receive timely and consistent updates on ADT-related activities in a standardized JSON format.
Each client must provide a valid HTTP POST endpoint where the webhook messages will be delivered. This endpoint can be configured via Webhook Configuration.
The configured endpoint will receive a payload that is similar to the example provided below:
{
    "id": "2f653bd7-d445-47d0-806a-5da8734427b6",
    "event": "ADT Summary",
    "message": "There were 8 new discharges. Please call the respective APIs for detailed information.",
    "timestamp": "2025-11-13T16:00:13Z",
    "endpoint": "api/v1/adtrecord/event-summaries/2f653bd7-d445-47d0-806a-5da8734427b6"
}

Assessment

API	Data	Endpoint
Templates	Returns a list of all assessment templates available for a specific facility, with the organization code and `ccn` (CMS Certification Number) passed in the request, provided the client identified via the token has access to the facility.	GET /api/v1/assessment/{org_code}/ {ccn}/templates Get Templates By Facility Id
Template	Returns the full structure and metadata of a specific assessment template, including its sections, question groups, individual questions, and possible response options, available for a specific facility, with the organization code, and `ccn` (CMS Certification Number) and template identifier passed in the request, provided the client identified via the token has access to the facility.	GET /api/v1/assessment/{org_code}/ {ccn}/templates/{template_id} Get Template By Id
Assessments	Returns a list of completed or in-progress assessment records for a given facility, including summary details like description, status, score, date, and which template/version they were based on, with the organization code and `ccn` (CMS Certification Number) passed in the request, provided the client identified via the token has access to the facility.	GET /api/v1/assessment/{org_code}/ {ccn}/assessments Get Assessments By Facility Id
Assessment	Returns the full details of a single completed or in-progress assessment record for a given facility, including summary details like description, status, score, date, and which template/version it was based on, with the organization code, and `ccn` (CMS Certification Number) and assessment identifier passed in the request, provided the client identified via the token has access to the facility.	GET /api/v1/assessment/{org_code}/ {ccn}/assessment/{assessment_id} Get Assessment By Id

Care Plan

API	Data	Endpoint
Care Plans	Returns a list of care plans, for a given patient within a facility, which outline patient-specific clinical goals, interventions, and statuses, often including multiple focuses (e.g., mobility, nutrition, safety), with the the organization code, and`ccn` (CMS Certification Number) and source patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/careplan/{org_code}/{ccn}/list Get Care Plans By Patient Id
Care Plan Kardex	Returns Care Plan Kardexes, for specific patients in a facility, which are quick-reference summary tools that provide clinicians with essential patient care instructions, categories, and tasks without needing to review the full care plan, with the organization code, and `ccn` (CMS Certification Number) and source patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/careplan/{org_code}/ {ccn}/kardex Get Care Plan Kardex By Patient Id
Care Plan Focus	Returns the detailed care plan items associated with a specific focus, within a patient’s care plan at a facility, which represents a clinical area or problem, with the organization code, and `ccn` (CMS Certification Number) and focus identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/careplan/{org_code}/ {ccn}/focus/{focus_id} Get Care Plan Focus By Focus Id

Conditions

API	Data	Endpoint
Conditions	Returns the list of a patient’s medical conditions (diagnoses) for the specified facility, including ICD-10 details, status, dates, and audit information, with the organization code, and `ccn` (CMS Certification Number) and source patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/condition/{org_code}/{ccn}/list Get Condtions By Facility Id

Documents

API	Data	Endpoint
Documents	Returns the list of patient documents stored within a facility under a given organization, with the organization code, and `ccn` (CMS Certification Number) and source patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/document/{org_code}/ {ccn}/list Get Documents List
Document File	Downloads a specific document file from the system for a given organization, facility, and patient, with the organization code, `ccn` (CMS Certification Number) and source patient and file identifiers passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/document/{org_code}/ {ccn}/download/{file_id} Download Document by File Id
Document Text	Retrieves the text content extracted from a specific document file associated with a given organization, facility, and patient, with the organization code, `ccn` (CMS Certification Number) and source patient and file identifiers passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/document/{org_code}/ {ccn}/text/{file_id} Get Document Text by File Id
Facility Documents	Retrieves a list of documents associated with a specific facility within an organization that includes metadata about each document, such as file name, category, and effective date, with the organization code, and `ccn` (CMS Certification Number) passed in the request, provided the client identified via the token has access to the facility.	GET /api/v1/document/{org_code}/ {ccn}/facility-documents Get Facility Documents List

Facility

API	Data	Endpoint
Facilities	Returns details for all facilities associated with the client identified via the token.	GET api/facility/list Get Facilities List
Facility	Returns details for the facility, with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/facility/{org_code}/ {ccn} Get Facility by Id
Facility Beds	Returns the list of beds for the facility, with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/facility/{org_code}/ {ccn}/beds Get Facility Beds
Facility Rooms	Returns the list of rooms for the facility, with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/facility/{org_code}/ {ccn}/rooms Get Facility Rooms
Facility Units	Returns the list of units for the facility, with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/facility/{org_code}/ {ccn}/units Get Facility Units
Facility Floors	Returns the list of floors for the facility, with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/facility/{org_code}/ {ccn}/floors Get Facility Floors

Observations

API	Data	Endpoint
Baselines	Returns a patient’s baseline clinical observation data (e.g., vitals or lab values) for a given facility, including measurement type, unit, value, thresholds, goals, method, and audit info like revision date, with the organization code, `ccn` (CMS Certification Number) and source patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/observation/{org_code}/ {ccn}/baselines Get Observation Baselines for Patient
Observations	Returns a list of a patient’s recorded clinical observations (e.g., vital signs or measurements) within a facility. Each record includes the observation type, value, unit, method, device used, who recorded it, when it was recorded, and any associated warnings, with the organization code, `ccn` (CMS Certification Number) and source patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/observation/{org_code}/ {ccn}/list Get Observations for Patient
Observation	Returns the full details of a specific clinical observation for a patient within a facility. The response includes observation type, measured value(s) (with units, e.g., systolic/diastolic), method, device information, who recorded it, when it was recorded, and any warnings linked to that observation, with the organization code, `ccn` (CMS Certification Number) and observation identifiers passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/observation/{org_code}/ {ccn}/{observation_id} Get Observation by ID

Patients

API	Data	Endpoint
Patient	Returns the patient details for the patient with the organization code, source patient identifier and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/patient/{org_code}/ {ccn}/{patient_id} Get Patient by PatientId
Patients	Returns the patient details for all patients for the facility with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/patient/{org_code}/ {ccn}/list Get Facility Patients
Patient Contacts	Retrieves the list of personal and emergency contacts associated with a specific patient, including demographic details, communication information, address, relationship, and contact role, with the organization code, `ccn` (CMS Certification Number), and patient identifier passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/patient/{org_code}/{ccn}/ {patient_id}/contacts Get Patient Contacts

Progress Notes

API	Data	Endpoint
Progress Notes Types	Returns the available progress note types, for a facility, each of which includes metadata such as whether it is high priority, its sections, and flags indicating if it should appear on the 24-hour report or shift report, with the organization code, and `ccn` (CMS Certification Number) passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/progress-note/{org_code}/ {ccn}/types Get Progress Note Types
Progress Notes	Returns progress notes, created for a specific patient within a facility, which typically document clinical observations, treatments, or events recorded during patient care, with the organization code, `ccn` (CMS Certification Number) and source patient identifiers passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/progress-note/{org_code}/ {ccn}/list Get Progress Notes
Progress Note	Returns the full details of a specific progress note, within a facility, which captures focused clinical documentation, including note type, structured sections, and coded classifications, with the organization code, `ccn` (CMS Certification Number) and progress note identifiers passed in the request provided the client identified via the token has access to the facility.	GET /api/v1/progress-note/{org_code}/ {ccn}/{progress_note_id} Get Progress Note By Id

Webhook Configuration

API	Data	Endpoint
Webhook URL	Retrieves the webhook configuration for the platform, including the destination URL and the secret key, which is attached in the header for signing webhook events.	GET /api/v1/webhook-config Get Webhook URL
Set Webhook URL	Updates the webhook configuration for the platform, including the destination URL and the secret key, which is attached in the header for signing webhook events.	POST /api/v1/webhook-config Update Webhook URL

❗
After the Set Webhook URL endpoint is called to update the webhook URL, z-PAX will send a test message (that is similar to the example provided below) to the provided URL.
{
  "id": "7237c284-6e49-4ae8-a69e-5ab89e2ef5a6",
  "event": "Webhook Validation",
  "message": "It's an autogenerated message to validate the url while trying to update the Webhook Configuration",
  "timestamp": "2025-11-14T10:47:37Z"
}
The system will update the webhook URL (and the secret key) in its configuration and return a 200 status only if it receives a successful 200 response from the target endpoint (the webhook URL). If the test message does not receive a 200 response, the update will fail and an error (400 status) will be returned.