Skip to content

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:

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

Active Endpoints

Pagination and Filtering ​

Pagination Parameters ​

ParameterTypeDefaultRangeDescription
limitinteger101–100Maximum number of records to return
offsetinteger00+Number of records to skip

Filtering Parameters ​

The following optional parameters can be combined with pagination:

ParameterApplies ToTypeDescription
startDatemedications, allergies, labs, notes, encounters, procedures, immunizations, vitals, socialHistory, familyHistory, careTeam, problemList, planOfCarestringStart 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
endDatemedications, allergies, labs, notes, encounters, procedures, immunizations, vitals, socialHistory, familyHistory, careTeamstringEnd 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
typeallergies, encounters, labs, notes, proceduresstringFilter 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
includeFileMetadataall record typesbooleanWhen 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 ​

json
{
  "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):

json
{
  "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:

json
{
  "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 ​

javascript
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 ​

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.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
allergenstringAllergen name (required)
startDatestringStart date (YYYY-MM-DD)
endDatestringEnd date (YYYY-MM-DD)
reactionsstringReaction descriptions
notestringAdditional notes
severitystringSeverity level (e.g., Mild, Moderate, Severe)
statusstringStatus (e.g., Active, Inactive)
typestringAllergy type (e.g., Medication, Food, Environmental)
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Care Team ​

List parsed care team data for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
teamMemberstringProvider/team member name (required)
npistringNational Provider Identifier (10 digits)
relationshipstringRelationship/role to patient (e.g., PCP, Specialist)
specialtystringProvider specialty (e.g., Family Medicine, Cardiology)
addressstringProvider address
phonestringContact phone number
startDatestringStart date of care relationship (YYYY-MM-DD)
endDatestringEnd date of care relationship (YYYY-MM-DD, nullable)
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Encounters ​

List parsed encounter data for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
fileIdstringReference to source file
datestringDate of encounter (YYYY-MM-DD)
typestringEncounter type (e.g., officeVisit)
descriptionstringEncounter description
diagnosisstringDiagnosis/reason for visit
facilityTextstringFacility name
providerTextstringProvider name
providerNpistringProvider NPI number
groupNpistringGroup NPI number
facilityOidstringFacility OID (Object Identifier)
codesarrayStandardized medical codes (SNOMED CT, CPT, ICD-10, etc.)
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)
reasonsForVisitarrayNested array of reason-for-visit objects (see below)
reasonsForReferralarrayNested array of reason-for-referral objects (see below)
dischargeInstructionsarrayNested array of discharge instruction objects (see below)
dischargeMedicationsarrayNested array of discharge medication objects (see below)
medicationsAdministeredarrayNested array of medications administered during encounter (see below)

Reason for Visit Object (nested in reasonsForVisit array):

FieldTypeDescription
idstringReason-for-visit record UUID
reasonstringPrimary reason for visit (required)
commentstringAdditional comment/notes about the reason (nullable)
onsetDatestringDate symptom or condition onset (YYYY-MM-DD, nullable)
encounterDatestringDate of the associated encounter (YYYY-MM-DD, nullable)
referralobjectReferral information if applicable (JSONB, nullable)

Reason for Referral Object (nested in reasonsForReferral array):

FieldTypeDescription
idstringReason-for-referral record UUID
reasonstringPrimary reason for referral
referringProviderstringName of referring provider (nullable)
referringProviderSpecialtystringSpecialty of referring provider (nullable)
referredToProviderstringProvider referred to (nullable)
referralDatestringDate of referral (YYYY-MM-DD, nullable)
diagnosesstringAssociated diagnoses (nullable)
statusstringReferral status (nullable)
notesstringAdditional notes (nullable)

Discharge Instruction Object (nested in dischargeInstructions array):

FieldTypeDescription
idstringDischarge instruction record UUID
noteTextstringDischarge instruction text
noteDatestringDate 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):

FieldTypeDescription
idstringMedication administered record UUID
namestringMedication name
sigstringSig / dosage instructions (nullable)
administeredstringDate administered (YYYY-MM-DD, nullable)

Family History ​

List parsed family history data for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
fileIdstringReference to source file
conditionstringMedical condition (required)
relationstringFamily relationship (e.g., Father, Mother, Sibling)
notesstringAdditional notes
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Immunizations ​

List parsed immunization records for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
immunizationstringVaccine/immunization name (required)
administrationDatesarrayArray of administration dates (YYYY-MM-DD)
doseValuestringDose value
doseUnitstringDose unit (e.g., mL)
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Labs ​

List parsed lab panels and diagnostic test results for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
namestringLab panel name
testDatestringDate of test (YYYY-MM-DD)
categorystringLab category (LABS, DIAGNOSTIC, UNKNOWN)
notesstringLab notes
fileIdstringReference to source file
codesarrayStandardized medical codes (LOINC, SNOMED CT, CPT, etc.)
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)
resultsarrayNested array of lab result objects (see below)

Lab Result Fields:

FieldTypeDescription
idstringResult UUID
labIdstringReference to parent lab ID
testNamestringName of the test
valuestringResult value
unitstringUnit of measurement
referenceRangestringReference range
statusstringStatus (Normal, Abnormal)
notesstringResult notes
codesarrayStandardized medical codes (LOINC, SNOMED CT, CPT, etc.)

Medications ​

List parsed medication data for the patient.

http
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 medications
  • null: 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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
namestringMedication name (required)
sigstringDosage/administration instructions
doseSizestringSize of single dose
doseUnitstringUnit of the dose (mg, mL, etc.)
doseCountstringTotal number of doses for this prescription
statusstringMedication status (Active, Completed, etc.)
refillsintegerNumber of refills
lastFillstringDate of last fill (YYYY-MM-DD)
dispensedstringFree 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.
sectionLoincstringSection 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.
startDatestringStart date (YYYY-MM-DD)
endDatestringEnd date (YYYY-MM-DD)
notestringAdditional notes
codesarrayStandardized medication codes (see Code Object structure below)
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Code Object (in codes array):

FieldTypeDescription
systemstringCode system URL (e.g., http://www.nlm.nih.gov/research/umls/rxnorm for RxNorm, http://hl7.org/fhir/sid/ndc for NDC)
codestringThe actual code value
displaystringHuman-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.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
fileIdstringReference to source file
noteDatestringClinical date the note was authored/signed (YYYY-MM-DD)
noteTypestringDocument classification (e.g., 'Consultation Note')
noteTextstringNote text content
sectionLoincstringLOINC section code
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Plan of Care ​

List parsed plan of care data for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
typestringType/title of plan (e.g., "Diabetes Management Plan")
datestringPlan date (YYYY-MM-DD)
planNotearrayArray of plan note objects with header and text fields
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate 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.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
problemNamestringProblem/diagnosis name (required)
startDatestringProblem onset date (YYYY-MM-DD)
resolvedDatestringDate problem was resolved (YYYY-MM-DD, nullable)
notedDatestringDate problem was noted/documented (YYYY-MM-DD)
statusstringProblem status (e.g., Active, Inactive, Resolved)
commentsstringAdditional clinical notes/comments
codesarrayStandardized diagnosis codes (see Code Object structure below)
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Code Object (in codes array):

FieldTypeDescription
systemstringCode system URL (e.g., http://snomed.info/sct for SNOMED CT, http://hl7.org/fhir/sid/icd-10-cm for ICD-10-CM)
codestringThe actual code value
displaystringHuman-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.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
namestringProcedure name
procedureDatestringDate of procedure (YYYY-MM-DD)
categorystringProcedure category (SURGERY, LABS, DIAGNOSTIC, etc.)
notesstringProcedure notes
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Social History ​

List parsed social history data for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
descriptionstringSocial history item description (required)
responsestringPatient's response/answer
quantitystringQuantity (e.g., number of cigarettes)
frequencystringFrequency (e.g., daily, weekly)
startDatestringStart date (YYYY-MM-DD)
stopDatestringStop date (YYYY-MM-DD)
recordedDatestringDate the history was recorded (YYYY-MM-DD)
notesstringAdditional notes
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Vitals ​

List parsed vital measurements for the patient.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
patientVitalMeasureIdstringRecord UUID
patientIdstringPatient ID
appointmentIdstringAssociated appointment ID
vitalMeasureAtstringDate/time vitals were measured (ISO 8601)
heartRatestringHeart rate value
heartRateUnitstringHeart rate unit (e.g., bpm (beats/min))
bloodPressurestringBlood pressure value as string (format: systolic/diastolic)
bloodPressureUnitstringBlood pressure unit (e.g., mmHg (millimeters of mercury))
bloodOxygenSaturationstringSpO2 value
bloodOxygenSaturationUnitstringSpO2 unit
weightstringWeight value
weightUnitstringWeight unit
heightstringHeight value
heightUnitstringHeight unit
bmistringBMI value
bmiUnitstringBMI unit
temperaturestringTemperature value
temperatureUnitstringTemperature unit
respiratoryRatestringRespiratory rate value
respiratoryRateUnitstringRespiratory rate unit
painLevelstringPain level value
painLevelUnitstringPain level unit
glucoseLevelstringGlucose level value
glucoseLevelUnitstringGlucose level unit
carbonDioxideLevelstringCO2 level value
carbonDioxideLevelUnitstringCO2 level unit (default: PaCO2)
electrocardiogramPathstringECG data path
electrocardiogramUnitstringECG unit
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate 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.

http
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 ​

json
{
  "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 ​

FieldTypeDescription
idstringRecord UUID
clientIdstringOwning client ID
patientIdstringPatient ID
itemstringGeneral history item/question
typestringCategory type (typically "general")
notestringPatient's response/answer
datestringDate recorded (YYYY-MM-DD)
fileIdstringReference to source file
fileNamestringSource document file name (only present when includeFileMetadata=true)
parentFacilitystringFacility that submitted the source file (only present when includeFileMetadata=true)
transactionDatestringDate source file was received (only present when includeFileMetadata=true)

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid request parameters
401UNAUTHORIZEDMissing authentication or invalid token
403FORBIDDENInsufficient scopes (need record:read)
404RESOURCE_NOT_FOUNDPatient not found
500INTERNAL_ERRORError 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.

Vivlio Health API Documentation