Medical Records
Access read-only patient medical records data. All medical record endpoints are read-only.
Authentication
Requires a Client token with scope record:read.
Read-Only Access
Medical record endpoints do not support write operations. These endpoints retrieve parsed clinical data from the patient's health information.
Overview
All endpoints follow the pattern:
GET /ext/latest/patients/{patientId}/records/{recordType}
Authorization: Bearer {token}All medical record endpoints support pagination and filtering (where applicable).
Each record includes a fileId field — the ID of the source document the record was parsed from. To also include fileName, parentFacility, and transactionDate from the source file, pass ?includeFileMetadata=true. These fields are absent from the response when the flag is omitted.
Standardized Codes
Select record types include a codes array with standardized medical codes (RxNorm, NDC, ICD-10, SNOMED CT, LOINC, CPT, etc.) extracted from source documents. Currently available for medications, problem list, encounters, and labs records.
Quick Links
Active Endpoints
- Allergies
- Care Team
- Encounters
- Family History
- History General
- Immunizations
- Labs
- Medications
- Notes
- Plan of Care
- Problem List
- Procedures
- Social History
- Vitals
Pagination and Filtering
Pagination Parameters
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
limit | integer | 10 | 1–100 | Maximum number of records to return |
offset | integer | 0 | 0+ | Number of records to skip |
Filtering Parameters
The following optional parameters can be combined with pagination:
| Parameter | Applies To | Type | Description |
|---|---|---|---|
startDate | medications, allergies, labs, notes, encounters, procedures, immunizations, vitals, socialHistory, familyHistory, careTeam, problemList, planOfCare | string | Start date range filter (YYYY-MM-DD). Use startDate=null to filter for records with no date. Can be used alone (≥ startDate) or with endDate for range filtering |
endDate | medications, allergies, labs, notes, encounters, procedures, immunizations, vitals, socialHistory, familyHistory, careTeam | string | End date range filter (YYYY-MM-DD). Can be used alone (≤ endDate) or with startDate for range filtering. Ignored when startDate=null. Not supported for problemList or planOfCare |
type | allergies, encounters, labs, notes, procedures | string | Filter by type (external API value). Values per endpoint: • Allergies: MEDICATION, FOOD, ENVIRONMENTAL • Encounters: OFFICE, HOSPITAL, TELEHEALTH • Labs: LABS, DIAGNOSTIC, UNKNOWN (category could not be determined) • Notes: PROGRESS, SURGERY, CONSULTATION, ANNUAL, VISIT, REFERRAL • Procedures: SURGERY, DIAGNOSTIC, LABS |
includeFileMetadata | all record types | boolean | When true, attaches fileName, parentFacility, and transactionDate from the source file to each record. Default: false. |
Date Filtering Modes
?startDate=2024-01-01— Records on or after Jan 1, 2024 (endDate optional)?endDate=2024-12-31— Records on or before Dec 31, 2024 (startDate optional)?startDate=2024-01-01&endDate=2024-12-31— Records between dates (inclusive range)?startDate=null— Records with NULL/missing dates only (endDate ignored)
Paginated Response Structure
{
"data": [ ... ],
"limit": 10,
"offset": 0,
"total": 156,
"hasMore": true
}File Metadata (includeFileMetadata=true)
Pass ?includeFileMetadata=true to attach source file information to each record. Example response for a medication:
Without flag (default):
{
"id": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"name": "acetaminophen (TYLENOL) 325 MG tablet",
"status": "Active",
"startDate": "2024-09-01",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}With ?includeFileMetadata=true:
{
"id": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"name": "acetaminophen (TYLENOL) 325 MG tablet",
"status": "Active",
"startDate": "2024-09-01",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef",
"fileName": "CCDA_ProgressNote_2024-09-01.xml",
"parentFacility": "Valley Medical Center",
"transactionDate": "2024-09-03T10:12:00.000Z"
}Code Examples
Node.js
async function getPatientMedications(token, patientId) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/patients/${patientId}/records/medications?limit=10`,
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.json();
}
async function getPatientAllergies(token, patientId) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/patients/${patientId}/records/allergies`,
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.json();
}
async function getOfficeVisits(token, patientId) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/patients/${patientId}/records/encounters?type=OFFICE&startDate=2024-01-01`,
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.json();
}Python
import requests
def get_medical_records(token, patient_id, record_type, **params):
"""Fetch medical records with optional filtering and pagination."""
response = requests.get(
f'https://api.vivliohealth.io/ext/latest/patients/{patient_id}/records/{record_type}',
headers={'Authorization': f'Bearer {token}'},
params=params
)
response.raise_for_status()
return response.json()
# Get all medications
medications = get_medical_records(token, patient_id, 'medications')
# Get office visits from 2024
office_visits = get_medical_records(
token, patient_id, 'encounters',
type='OFFICE',
startDate='2024-01-01',
endDate='2024-12-31',
limit=20
)
# Get allergies with pagination
allergies = get_medical_records(
token, patient_id, 'allergies',
limit=10,
offset=10
)Active Endpoints
Allergies
List parsed allergy data for the patient.
GET /ext/latest/patients/{patientId}/records/allergies
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Supports type filtering: ?type=MEDICATION — Values: MEDICATION, FOOD, ENVIRONMENTAL
Usage Examples
- Get all allergies:
GET /patients/{patientId}/records/allergies - Get medication allergies:
GET /patients/{patientId}/records/allergies?type=MEDICATION - Get environmental allergies:
GET /patients/{patientId}/records/allergies?type=ENVIRONMENTAL - Get allergies recorded since 2023:
GET /patients/{patientId}/records/allergies?startDate=2023-01-01&limit=10
Sample Response
{
"data": [
{
"id": "019d0716-7b44-70af-9ef4-60d2dd3057ec",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"allergen": "Penicillin",
"startDate": "2020-03-15",
"endDate": null,
"reactions": "Hives, Rash",
"note": null,
"severity": "Moderate",
"status": "Active",
"type": "Medication",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 1,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
allergen | string | Allergen name (required) |
startDate | string | Start date (YYYY-MM-DD) |
endDate | string | End date (YYYY-MM-DD) |
reactions | string | Reaction descriptions |
note | string | Additional notes |
severity | string | Severity level (e.g., Mild, Moderate, Severe) |
status | string | Status (e.g., Active, Inactive) |
type | string | Allergy type (e.g., Medication, Food, Environmental) |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Care Team
List parsed care team data for the patient.
GET /ext/latest/patients/{patientId}/records/careTeam
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD (filters by care relationship start/end dates)
Usage Examples
- Get all care team members:
GET /patients/{patientId}/records/careTeam - Get care team members with dates:
GET /patients/{patientId}/records/careTeam?startDate=2024-01-01&endDate=2024-12-31 - Get paginated care team:
GET /patients/{patientId}/records/careTeam?limit=5&offset=0
Sample Response
{
"data": [
{
"id": "019d0716-c177-70af-9ef4-9e24f8047e12",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"teamMember": "Dr. Sarah Johnson",
"npi": "1234567890",
"relationship": "Primary Care Physician",
"specialty": "Family Medicine",
"address": "123 Medical Center Dr, Springfield, MA 01101",
"phone": "555-123-4567",
"startDate": "2023-01-15",
"endDate": null,
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 3,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
teamMember | string | Provider/team member name (required) |
npi | string | National Provider Identifier (10 digits) |
relationship | string | Relationship/role to patient (e.g., PCP, Specialist) |
specialty | string | Provider specialty (e.g., Family Medicine, Cardiology) |
address | string | Provider address |
phone | string | Contact phone number |
startDate | string | Start date of care relationship (YYYY-MM-DD) |
endDate | string | End date of care relationship (YYYY-MM-DD, nullable) |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Encounters
List parsed encounter data for the patient.
GET /ext/latest/patients/{patientId}/records/encounters
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Supports type filtering: ?type=OFFICE — Values: OFFICE, HOSPITAL, TELEHEALTH
Usage Examples
- Get all encounters:
GET /patients/{patientId}/records/encounters - Get office visits:
GET /patients/{patientId}/records/encounters?type=OFFICE - Get hospital encounters:
GET /patients/{patientId}/records/encounters?type=HOSPITAL - Get telehealth visits from 2024:
GET /patients/{patientId}/records/encounters?type=TELEHEALTH&startDate=2024-01-01 - Get office visits with pagination:
GET /patients/{patientId}/records/encounters?type=OFFICE&limit=10&offset=20
Sample Response
{
"data": [
{
"id": "019d0716-8c55-70af-9ef4-70e3ee4068fd",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef",
"date": "2025-06-10",
"type": "officeVisit",
"description": "Medication review",
"diagnosis": "Chronic condition management",
"facilityText": "Valley Medical Center",
"providerText": null,
"providerNpi": "1111111111",
"groupNpi": "2222222222",
"facilityOid": "2.16.840.1.113883.4.6",
"codes": [
{
"system": "http://snomed.info/sct",
"code": "185349003",
"display": "Encounter for check up (procedure)"
},
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "99213",
"display": "Office outpatient visit 15 minutes"
}
],
"reasonsForVisit": [
{
"id": "019d0716-8c55-70af-9ef4-80f4ff5179fe",
"reason": "Follow-up appointment",
"comment": "Patient requested medication review",
"onsetDate": "2025-06-05",
"encounterDate": "2025-06-10",
"referral": null
}
],
"reasonsForReferral": [
{
"id": "019d0716-8c55-70af-9ef4-92b6aa3210cd",
"reason": "Specialist evaluation for chronic pain",
"referringProvider": "Dr. Smith",
"referringProviderSpecialty": "Internal Medicine",
"referredToProvider": "Dr. Jones",
"referralDate": "2025-06-10",
"diagnoses": "Chronic lower back pain",
"status": "active",
"notes": "Patient reports worsening symptoms over 3 months"
}
],
"dischargeInstructions": [
{
"id": "019d0716-8c55-70af-9ef4-a1b2cc4567ef",
"noteText": "<paragraph><content>Follow up with primary care in 2 weeks. Take prescribed medications as directed.</content></paragraph>",
"noteDate": "2025-06-10"
}
],
"dischargeMedications": [
{
"id": "019d0716-8c55-70af-9ef4-b3c4dd5678ab",
"name": "Ibuprofen 400mg",
"sig": "Take 1 tablet by mouth every 6 hours as needed",
"doseSize": "400",
"doseUnit": "mg",
"status": "active",
"refills": "2",
"lastFill": null,
"startDate": "2025-06-10",
"endDate": null,
"note": null,
"dispensed": null
}
],
"medicationsAdministered": [
{
"id": "019d0716-8c55-70af-9ef4-c4d5ee6789bc",
"name": "Normal Saline 0.9% IV",
"sig": "1000mL IV over 2 hours",
"administered": "2025-06-10"
}
]
}
],
"limit": 10,
"offset": 0,
"total": 16,
"hasMore": true
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
fileId | string | Reference to source file |
date | string | Date of encounter (YYYY-MM-DD) |
type | string | Encounter type (e.g., officeVisit) |
description | string | Encounter description |
diagnosis | string | Diagnosis/reason for visit |
facilityText | string | Facility name |
providerText | string | Provider name |
providerNpi | string | Provider NPI number |
groupNpi | string | Group NPI number |
facilityOid | string | Facility OID (Object Identifier) |
codes | array | Standardized medical codes (SNOMED CT, CPT, ICD-10, etc.) |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
reasonsForVisit | array | Nested array of reason-for-visit objects (see below) |
reasonsForReferral | array | Nested array of reason-for-referral objects (see below) |
dischargeInstructions | array | Nested array of discharge instruction objects (see below) |
dischargeMedications | array | Nested array of discharge medication objects (see below) |
medicationsAdministered | array | Nested array of medications administered during encounter (see below) |
Reason for Visit Object (nested in reasonsForVisit array):
| Field | Type | Description |
|---|---|---|
id | string | Reason-for-visit record UUID |
reason | string | Primary reason for visit (required) |
comment | string | Additional comment/notes about the reason (nullable) |
onsetDate | string | Date symptom or condition onset (YYYY-MM-DD, nullable) |
encounterDate | string | Date of the associated encounter (YYYY-MM-DD, nullable) |
referral | object | Referral information if applicable (JSONB, nullable) |
Reason for Referral Object (nested in reasonsForReferral array):
| Field | Type | Description |
|---|---|---|
id | string | Reason-for-referral record UUID |
reason | string | Primary reason for referral |
referringProvider | string | Name of referring provider (nullable) |
referringProviderSpecialty | string | Specialty of referring provider (nullable) |
referredToProvider | string | Provider referred to (nullable) |
referralDate | string | Date of referral (YYYY-MM-DD, nullable) |
diagnoses | string | Associated diagnoses (nullable) |
status | string | Referral status (nullable) |
notes | string | Additional notes (nullable) |
Discharge Instruction Object (nested in dischargeInstructions array):
| Field | Type | Description |
|---|---|---|
id | string | Discharge instruction record UUID |
noteText | string | Discharge instruction text |
noteDate | string | Date of discharge instruction (YYYY-MM-DD, nullable) |
Discharge Medication Object (nested in dischargeMedications array):
| Field | Type | Description | |-------------|--------|--------------------------------------------------------------------|| | id | string | Medication record UUID | | name | string | Medication name | | sig | string | Sig / dosage instructions (nullable) | | doseSize | string | Dose amount (nullable) | | doseUnit | string | Dose unit of measure (nullable) | | status | string | Medication status (nullable) | | refills | string | Number of refills (nullable) | | lastFill | string | Date of last fill (nullable) | | startDate | string | Medication start date (YYYY-MM-DD, nullable) | | endDate | string | Medication end date (YYYY-MM-DD, nullable) | | note | string | Additional notes (nullable) | | dispensed | string | Free text copied from the dispense column of the source document (nullable). Depending on the source system, it is a dispensed quantity (for example "30 capsule") or a count of fills dispensed. null when the source document has no such value. It does not confirm that the patient picked up or took the drug. |
Medication Administered Object (nested in medicationsAdministered array):
| Field | Type | Description |
|---|---|---|
id | string | Medication administered record UUID |
name | string | Medication name |
sig | string | Sig / dosage instructions (nullable) |
administered | string | Date administered (YYYY-MM-DD, nullable) |
Family History
List parsed family history data for the patient.
GET /ext/latest/patients/{patientId}/records/familyHistory
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Usage Examples
- Get all family history:
GET /patients/{patientId}/records/familyHistory - Get family history from 2020 onward:
GET /patients/{patientId}/records/familyHistory?startDate=2020-01-01 - Get paginated family history:
GET /patients/{patientId}/records/familyHistory?limit=5&offset=0
Sample Response
{
"data": [
{
"id": "019d0716-d099-70af-9ef4-b3c722840c11",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef",
"condition": "Type 2 Diabetes Mellitus",
"relation": "Father",
"notes": null
}
],
"limit": 10,
"offset": 0,
"total": 3,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
fileId | string | Reference to source file |
condition | string | Medical condition (required) |
relation | string | Family relationship (e.g., Father, Mother, Sibling) |
notes | string | Additional notes |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Immunizations
List parsed immunization records for the patient.
GET /ext/latest/patients/{patientId}/records/immunizations
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD (filters records where ANY administration date falls within the range)
Usage Examples
- Get all immunizations:
GET /patients/{patientId}/records/immunizations - Get recent immunizations:
GET /patients/{patientId}/records/immunizations?limit=5 - Get immunizations from 2024:
GET /patients/{patientId}/records/immunizations?startDate=2024-01-01&endDate=2024-12-31 - Get immunizations with pagination:
GET /patients/{patientId}/records/immunizations?limit=10&offset=10
Sample Response
{
"data": [
{
"id": "019ef4ba-34b1-7006-81a1-5a3929d4a245",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"immunization": "Meningococcal Vaccine",
"administrationDates": ["2025-04-12", "2025-05-12"],
"doseValue": "0.5",
"doseUnit": "mL",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 2,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
immunization | string | Vaccine/immunization name (required) |
administrationDates | array | Array of administration dates (YYYY-MM-DD) |
doseValue | string | Dose value |
doseUnit | string | Dose unit (e.g., mL) |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Labs
List parsed lab panels and diagnostic test results for the patient.
GET /ext/latest/patients/{patientId}/records/labs
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y (pagination applies to parent labs; all nested results returned)
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Supports type filtering: ?type=LABS — Values: LABS, DIAGNOSTIC, UNKNOWN (labs whose category could not be determined)
Usage Examples
- Get all labs:
GET /patients/{patientId}/records/labs - Get labs only:
GET /patients/{patientId}/records/labs?type=LABS - Get diagnostic tests:
GET /patients/{patientId}/records/labs?type=DIAGNOSTIC - Get labs with undetermined category:
GET /patients/{patientId}/records/labs?type=UNKNOWN - Get labs from date range:
GET /patients/{patientId}/records/labs?startDate=2023-01-01&endDate=2023-12-31&type=LABS - Get labs with pagination:
GET /patients/{patientId}/records/labs?limit=10&offset=20
Sample Response
{
"data": [
{
"id": "cf1dbb7f-1a13-4794-9c6c-2549ced9309f",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"name": "Hemoglobin A1C",
"testDate": "2025-05-22",
"notes": null,
"category": "LABS",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef",
"codes": [
{
"system": "http://loinc.org",
"code": "4548-4",
"display": "Hemoglobin A1c/Hemoglobin.total in Blood"
}
],
"results": [
{
"id": "result-uuid-1",
"labId": "cf1dbb7f-1a13-4794-9c6c-2549ced9309f",
"testName": "Hemoglobin A1C",
"value": "6.8",
"unit": "%",
"referenceRange": "< 5.7",
"status": "Abnormal",
"notes": null,
"codes": [
{
"system": "http://loinc.org",
"code": "4548-4",
"display": "Hemoglobin A1c/Hemoglobin.total in Blood"
}
]
}
]
}
],
"limit": 10,
"offset": 0,
"total": 4,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
name | string | Lab panel name |
testDate | string | Date of test (YYYY-MM-DD) |
category | string | Lab category (LABS, DIAGNOSTIC, UNKNOWN) |
notes | string | Lab notes |
fileId | string | Reference to source file |
codes | array | Standardized medical codes (LOINC, SNOMED CT, CPT, etc.) |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
results | array | Nested array of lab result objects (see below) |
Lab Result Fields:
| Field | Type | Description |
|---|---|---|
id | string | Result UUID |
labId | string | Reference to parent lab ID |
testName | string | Name of the test |
value | string | Result value |
unit | string | Unit of measurement |
referenceRange | string | Reference range |
status | string | Status (Normal, Abnormal) |
notes | string | Result notes |
codes | array | Standardized medical codes (LOINC, SNOMED CT, CPT, etc.) |
Medications
List parsed medication data for the patient.
GET /ext/latest/patients/{patientId}/records/medications
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Medication List and Discharge Rows
This endpoint returns rows from two sections of the source document in one list: the patient's medication list and the medications prescribed at hospital discharge. There is no parameter to filter by section. The sectionLoinc field tells the rows apart:
10160-0: the medication list (LOINC "History of medication use")10183-2: hospital discharge medicationsnull: the section is unknown. Read the row as neither one.
The discharge rows also appear, with the same id, in dischargeMedications on the Encounters endpoint. A client that combines the two lists should de-duplicate by id.
Usage Examples
- Get all medications:
GET /patients/{patientId}/records/medications - Get first 5 medications:
GET /patients/{patientId}/records/medications?limit=5 - Get medications from January 2024:
GET /patients/{patientId}/records/medications?startDate=2024-01-01&endDate=2024-01-31 - Get active medications only (pagination):
GET /patients/{patientId}/records/medications?limit=10&offset=20
Sample Response
{
"data": [
{
"id": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"name": "acetaminophen (TYLENOL) 325 MG tablet",
"sig": "Take 2 tablets by mouth Every 6 Hours As Needed for Mild Pain.",
"doseSize": "650",
"doseUnit": "mg",
"doseCount": null,
"status": "Active",
"refills": 0,
"lastFill": null,
"dispensed": "60 tablet",
"sectionLoinc": "10160-0",
"startDate": "2024-09-01",
"endDate": null,
"note": null,
"codes": [
{
"system": "http://www.nlm.nih.gov/research/umls/rxnorm",
"code": "313782",
"display": "Acetaminophen 325 MG Oral Tablet"
},
{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "50580-0506-01",
"display": null
}
],
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 5,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
name | string | Medication name (required) |
sig | string | Dosage/administration instructions |
doseSize | string | Size of single dose |
doseUnit | string | Unit of the dose (mg, mL, etc.) |
doseCount | string | Total number of doses for this prescription |
status | string | Medication status (Active, Completed, etc.) |
refills | integer | Number of refills |
lastFill | string | Date of last fill (YYYY-MM-DD) |
dispensed | string | Free text copied from the dispense column of the source document (nullable). Depending on the source system, it is a dispensed quantity (for example "30 capsule") or a count of fills dispensed. null when the source document has no such value. It does not confirm that the patient picked up or took the drug. |
sectionLoinc | string | Section of the source document the row came from (nullable): 10160-0 for the medication list, 10183-2 for hospital discharge medications, null when the section is unknown. See Medication List and Discharge Rows. |
startDate | string | Start date (YYYY-MM-DD) |
endDate | string | End date (YYYY-MM-DD) |
note | string | Additional notes |
codes | array | Standardized medication codes (see Code Object structure below) |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Code Object (in codes array):
| Field | Type | Description |
|---|---|---|
system | string | Code system URL (e.g., http://www.nlm.nih.gov/research/umls/rxnorm for RxNorm, http://hl7.org/fhir/sid/ndc for NDC) |
code | string | The actual code value |
display | string | Human-readable description of the code (nullable) |
Common code systems for medications:
- RxNorm (
http://www.nlm.nih.gov/research/umls/rxnorm) - Semantic drug codes - NDC (
http://hl7.org/fhir/sid/ndc) - National Drug Code (package-level identifiers) - NDDF (
http://hl7.org/fhir/sid/nddf) - First Databank drug codes - SNOMED CT (
http://snomed.info/sct) - Clinical terminology codes
Notes
List parsed clinical note data for the patient.
GET /ext/latest/patients/{patientId}/records/notes
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Supports type filtering: ?type=SURGERY — Values: PROGRESS, SURGERY, CONSULTATION, ANNUAL, VISIT, REFERRAL
Usage Examples
- Get all notes:
GET /patients/{patientId}/records/notes - Get surgical notes:
GET /patients/{patientId}/records/notes?type=SURGERY - Get progress notes:
GET /patients/{patientId}/records/notes?type=PROGRESS - Get consultation notes from 2024:
GET /patients/{patientId}/records/notes?type=CONSULTATION&startDate=2024-01-01 - Get notes from specific date:
GET /patients/{patientId}/records/notes?startDate=2024-01-01 - Get notes with no date:
GET /patients/{patientId}/records/notes?startDate=null - Combined filters:
GET /patients/{patientId}/records/notes?type=PROGRESS&startDate=2024-01-01&limit=10
Sample Response
{
"data": [
{
"id": "019d0716-9d66-70af-9ef4-80f4ff5179fe",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef",
"noteType": "Consultation Note",
"sectionLoinc": null,
"noteDate": "2026-02-16",
"noteText": "Patient referred for cardiology evaluation. History of hypertension and elevated cholesterol. Physical exam unremarkable. Recommend stress testing."
}
],
"limit": 10,
"offset": 0,
"total": 8,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
fileId | string | Reference to source file |
noteDate | string | Clinical date the note was authored/signed (YYYY-MM-DD) |
noteType | string | Document classification (e.g., 'Consultation Note') |
noteText | string | Note text content |
sectionLoinc | string | LOINC section code |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Plan of Care
List parsed plan of care data for the patient.
GET /ext/latest/patients/{patientId}/records/planOfCare
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD (filters by plan date; endDate not supported for this endpoint)
Usage Examples
- Get all care plans:
GET /patients/{patientId}/records/planOfCare - Get care plans from 2024:
GET /patients/{patientId}/records/planOfCare?startDate=2024-01-01 - Get first 5 care plans:
GET /patients/{patientId}/records/planOfCare?limit=5&offset=0
Sample Response
{
"data": [
{
"id": "019d0716-e321-70af-9ef4-d5e944a62e34",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"type": "Diabetes Management Plan",
"date": "2024-07-20",
"planNote": [
{
"header": "Monitoring",
"text": "Check HbA1c every 3 months. Target < 7%."
},
{
"header": "Medications",
"text": "Continue metformin 1000mg BID. Add linagliptin if HbA1c not at goal."
},
{
"header": "Lifestyle",
"text": "Refer to dietitian for medical nutrition therapy. Recommend 150 min/week moderate exercise."
}
],
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 2,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
type | string | Type/title of plan (e.g., "Diabetes Management Plan") |
date | string | Plan date (YYYY-MM-DD) |
planNote | array | Array of plan note objects with header and text fields |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Plan Note Structure:
Each object in the planNote array has:
header— string, section title (e.g., "Monitoring", "Medications", "Follow-up")text— string, section content with instructions or recommendations
Problem List
List parsed problem list data for the patient.
GET /ext/latest/patients/{patientId}/records/problemList
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD (filters by problem onset date; endDate not supported for this endpoint)
Usage Examples
- Get all problems:
GET /patients/{patientId}/records/problemList - Get problems noted in 2024:
GET /patients/{patientId}/records/problemList?startDate=2024-01-01 - Get first 5 problems:
GET /patients/{patientId}/records/problemList?limit=5
Sample Response
{
"data": [
{
"id": "019d0716-d210-70af-9ef4-c4d833951d23",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"problemName": "Type 2 Diabetes Mellitus",
"startDate": "2015-03-10",
"resolvedDate": null,
"notedDate": "2024-06-15",
"status": "Active",
"comments": "Well-controlled with metformin monotherapy",
"codes": [
{
"system": "http://snomed.info/sct",
"code": "44054006",
"display": "Type 2 Diabetes Mellitus"
},
{
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "E11.9",
"display": "Type 2 diabetes mellitus without complications"
}
],
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 7,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
problemName | string | Problem/diagnosis name (required) |
startDate | string | Problem onset date (YYYY-MM-DD) |
resolvedDate | string | Date problem was resolved (YYYY-MM-DD, nullable) |
notedDate | string | Date problem was noted/documented (YYYY-MM-DD) |
status | string | Problem status (e.g., Active, Inactive, Resolved) |
comments | string | Additional clinical notes/comments |
codes | array | Standardized diagnosis codes (see Code Object structure below) |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Code Object (in codes array):
| Field | Type | Description |
|---|---|---|
system | string | Code system URL (e.g., http://snomed.info/sct for SNOMED CT, http://hl7.org/fhir/sid/icd-10-cm for ICD-10-CM) |
code | string | The actual code value |
display | string | Human-readable description of the code (nullable) |
Common code systems for diagnoses:
- SNOMED CT (
http://snomed.info/sct) - Clinical terminology for diagnoses and conditions - ICD-10-CM (
http://hl7.org/fhir/sid/icd-10-cm) - Diagnosis codes for billing and coding - ICD-9-CM (
http://hl7.org/fhir/sid/icd-9-cm) - Legacy diagnosis codes (historical data)
Procedures
List parsed surgery/procedure data for the patient.
GET /ext/latest/patients/{patientId}/records/procedures
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Supports type filtering: ?type=SURGERY — Values: SURGERY, DIAGNOSTIC, LABS
Usage Examples
- Get all procedures:
GET /patients/{patientId}/records/procedures - Get surgical procedures:
GET /patients/{patientId}/records/procedures?type=SURGERY - Get diagnostic procedures from 2024:
GET /patients/{patientId}/records/procedures?type=DIAGNOSTIC&startDate=2024-01-01 - Get lab procedures:
GET /patients/{patientId}/records/procedures?type=LABS
Sample Response
{
"data": [
{
"id": "019d0716-ae77-70af-9ef4-91a500628aef",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"name": "Colonoscopy and Biopsy",
"procedureDate": "2024-09-09",
"category": "SURGERY",
"notes": "Screening for colon cancer. Constipation, unspecified.",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 1,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
name | string | Procedure name |
procedureDate | string | Date of procedure (YYYY-MM-DD) |
category | string | Procedure category (SURGERY, LABS, DIAGNOSTIC, etc.) |
notes | string | Procedure notes |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Social History
List parsed social history data for the patient.
GET /ext/latest/patients/{patientId}/records/socialHistory
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Usage Examples
- Get all social history:
GET /patients/{patientId}/records/socialHistory - Get social history from 2020 onward:
GET /patients/{patientId}/records/socialHistory?startDate=2020-01-01 - Get social history with pagination:
GET /patients/{patientId}/records/socialHistory?limit=10&offset=10
Sample Response
{
"data": [
{
"id": "019d0716-bf88-70af-9ef4-a2b611739b00",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"description": "Tobacco use",
"response": "Former smoker, quit 2018",
"quantity": "10",
"frequency": "daily",
"startDate": "2005-01-01",
"stopDate": "2018-06-15",
"recordedDate": "2026-03-20",
"notes": null,
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 1,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
description | string | Social history item description (required) |
response | string | Patient's response/answer |
quantity | string | Quantity (e.g., number of cigarettes) |
frequency | string | Frequency (e.g., daily, weekly) |
startDate | string | Start date (YYYY-MM-DD) |
stopDate | string | Stop date (YYYY-MM-DD) |
recordedDate | string | Date the history was recorded (YYYY-MM-DD) |
notes | string | Additional notes |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Vitals
List parsed vital measurements for the patient.
GET /ext/latest/patients/{patientId}/records/vitals
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Usage Examples
- Get all vitals:
GET /patients/{patientId}/records/vitals - Get recent vitals:
GET /patients/{patientId}/records/vitals?limit=5 - Get vitals from 2024:
GET /patients/{patientId}/records/vitals?startDate=2024-01-01&endDate=2024-12-31 - Get vitals with pagination:
GET /patients/{patientId}/records/vitals?limit=10&offset=20
Sample Response
{
"data": [
{
"patientVitalMeasureId": "f9e8d7c6-5b4a-3210-fedc-ba0987654321",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"appointmentId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"vitalMeasureAt": "2026-02-16T14:30:00.000Z",
"heartRate": "72",
"heartRateUnit": "bpm (beats/min)",
"bloodPressure": "120/80",
"bloodPressureUnit": "mmHg (millimeters of mercury)",
"bloodOxygenSaturation": "98",
"bloodOxygenSaturationUnit": "%",
"weight": "185",
"weightUnit": "lbs",
"height": "70",
"heightUnit": "in",
"bmi": "26.5",
"bmiUnit": "kg/m2",
"temperature": "98.6",
"temperatureUnit": "F",
"respiratoryRate": "16",
"respiratoryRateUnit": "breaths/min",
"painLevel": null,
"painLevelUnit": null,
"glucoseLevel": null,
"glucoseLevelUnit": null,
"carbonDioxideLevel": null,
"carbonDioxideLevelUnit": null,
"electrocardiogramPath": null,
"electrocardiogramUnit": null,
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 0,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
patientVitalMeasureId | string | Record UUID |
patientId | string | Patient ID |
appointmentId | string | Associated appointment ID |
vitalMeasureAt | string | Date/time vitals were measured (ISO 8601) |
heartRate | string | Heart rate value |
heartRateUnit | string | Heart rate unit (e.g., bpm (beats/min)) |
bloodPressure | string | Blood pressure value as string (format: systolic/diastolic) |
bloodPressureUnit | string | Blood pressure unit (e.g., mmHg (millimeters of mercury)) |
bloodOxygenSaturation | string | SpO2 value |
bloodOxygenSaturationUnit | string | SpO2 unit |
weight | string | Weight value |
weightUnit | string | Weight unit |
height | string | Height value |
heightUnit | string | Height unit |
bmi | string | BMI value |
bmiUnit | string | BMI unit |
temperature | string | Temperature value |
temperatureUnit | string | Temperature unit |
respiratoryRate | string | Respiratory rate value |
respiratoryRateUnit | string | Respiratory rate unit |
painLevel | string | Pain level value |
painLevelUnit | string | Pain level unit |
glucoseLevel | string | Glucose level value |
glucoseLevelUnit | string | Glucose level unit |
carbonDioxideLevel | string | CO2 level value |
carbonDioxideLevelUnit | string | CO2 level unit (default: PaCO2) |
electrocardiogramPath | string | ECG data path |
electrocardiogramUnit | string | ECG unit |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
History General
List parsed general medical history data for the patient. This endpoint provides general questionnaire responses and medical history information that don't fit into specific categories like tobacco use, alcohol use, or occupation.
GET /ext/latest/patients/{patientId}/records/historyGeneral
Authorization: Bearer {token}Supports pagination: ?limit=X&offset=Y
Supports date filtering: ?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Usage Examples
- Get all general history:
GET /patients/{patientId}/records/historyGeneral - Get general history from 2024:
GET /patients/{patientId}/records/historyGeneral?startDate=2024-01-01 - Get recent general history:
GET /patients/{patientId}/records/historyGeneral?limit=5
Sample Response
{
"data": [
{
"id": "019d0716-c288-70af-9ef4-b4d722951e45",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"item": "General health assessment",
"type": "general",
"note": "Patient denies recent hospitalizations or surgeries",
"date": "2025-03-15",
"fileId": "019d0716-ae77-70af-9ef4-91a500628aef"
}
],
"limit": 10,
"offset": 0,
"total": 4,
"hasMore": false
}Field Reference
| Field | Type | Description |
|---|---|---|
id | string | Record UUID |
clientId | string | Owning client ID |
patientId | string | Patient ID |
item | string | General history item/question |
type | string | Category type (typically "general") |
note | string | Patient's response/answer |
date | string | Date recorded (YYYY-MM-DD) |
fileId | string | Reference to source file |
fileName | string | Source document file name (only present when includeFileMetadata=true) |
parentFacility | string | Facility that submitted the source file (only present when includeFileMetadata=true) |
transactionDate | string | Date source file was received (only present when includeFileMetadata=true) |
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid request parameters |
| 401 | UNAUTHORIZED | Missing authentication or invalid token |
| 403 | FORBIDDEN | Insufficient scopes (need record:read) |
| 404 | RESOURCE_NOT_FOUND | Patient not found |
| 500 | INTERNAL_ERROR | Error processing medical records |
Empty Results
If a patient has no records of a given type, the response returns an empty data array ([]), not an error. Pagination metadata is still included.
Records arrive only after a records query runs for the patient. A 200 with total: 0 before any query has run means "not queried yet", not "no history". To start a query, create an appointment. See Starting a Records Query.
