Patient Files
Access patient files and documents.
Authentication
Requires a Client token with scope file:read.
Read-Only Access
File endpoints do not support write operations. These endpoints retrieve metadata and access to patient files.
File pull activation required
File pull (retrieving patient documents from the health information network) requires your account to be activated by Vivlio Health after EPIC approval. Files will not be available until that activation is complete. See Client Onboarding and File Pull Activation for the full workflow.
Endpoints
List Patient Files
GET /ext/latest/patients/{patientId}/files
Authorization: Bearer {token}Query Parameters:
limit(optional) — Page size (default: 10, max: 100)offset(optional) — Page offset (default: 0)
Response:
{
"data": [
{
"fileId": "file-uuid-1",
"fileName": "lab_results_2024.pdf",
"documentTitle": "Lab Results",
"documentAuthor": "Dr. Jane Smith",
"dateOfService": "2024-09-12",
"facility": "Riverside Medical Center",
"parentFacility": "Riverside Health System",
"fileStatus": "Complete",
"fileSize": 1024000,
"createdAt": "2024-09-15",
"updatedAt": "2024-09-15T10:30:00.000Z",
"s3Key": "clients/9c1e.../file-uuid-1.pdf"
},
{
"fileId": "file-uuid-2",
"fileName": "imaging_scan.jpg",
"documentTitle": "Imaging Scan",
"documentAuthor": "Dr. John Doe",
"dateOfService": null,
"facility": "Riverside Medical Center",
"parentFacility": "Riverside Health System",
"fileStatus": "Complete",
"fileSize": 2048576,
"createdAt": "2024-09-10",
"updatedAt": "2024-09-10T14:20:00.000Z",
"s3Key": "clients/9c1e.../file-uuid-2.jpg"
}
],
"limit": 10,
"offset": 0,
"hasMore": false
}TIP
The list response does not include downloadUrl — request the file individually (below) to get a download link.
Get Specific File
GET /ext/latest/patients/{patientId}/files/{fileId}
Authorization: Bearer {token}Response:
{
"data": {
"fileId": "file-uuid-1",
"fileName": "lab_results_2024.pdf",
"documentTitle": "Lab Results",
"documentAuthor": "Dr. Jane Smith",
"dateOfService": "2024-09-12",
"facility": "Riverside Medical Center",
"parentFacility": "Riverside Health System",
"fileStatus": "Complete",
"fileSize": 1024000,
"createdAt": "2024-09-15",
"updatedAt": "2024-09-15T10:30:00.000Z",
"s3Key": "clients/9c1e.../file-uuid-1.pdf",
"downloadUrl": "https://clinical-data-vivlio-health-prod.s3.us-east-2.amazonaws.com/clients/9c1e.../file-uuid-1.pdf?X-Amz-Algorithm=...",
"downloadUrlExpiresAt": "2026-08-26T13:35:00.000Z"
}
}File Object Fields
| Field | Type | Description |
|---|---|---|
fileId | string | System-generated file UUID |
fileName | string | Original file name |
documentTitle | string | Document title (falls back to fileName if not set) |
documentAuthor | string | Document author, when known |
dateOfService | string | Date of service the document relates to (YYYY-MM-DD); null when unknown |
facility | string | Facility the file was retrieved from |
parentFacility | string | Parent health system/facility; null when unknown |
fileStatus | string | Processing status of the file |
fileSize | number | File size in bytes |
createdAt | string | Date the file record was created (YYYY-MM-DD) |
updatedAt | string | Last-updated timestamp (ISO 8601) |
s3Key | string | Internal storage key — not directly downloadable; use downloadUrl instead |
downloadUrl | string | Pre-signed S3 URL for downloading the file. Only present on the single-file GET /files/{fileId} response, and only when the file has a stored object (s3Key present). Expires after 5 minutes. |
downloadUrlExpiresAt | string | downloadUrl expiration time (ISO 8601) |
Additional fields
The API may return other implementation fields beyond those listed above. Treat any field not documented here as unstable — it may change without notice.
Supported File Types
Common supported file types include:
- Documents — PDF, Word (.docx), Text (.txt)
- Images — JPEG, PNG, GIF, TIFF
- Archives — ZIP
- Clinical — HL7, CDA, DICOM (format-specific support may vary)
File Type Support
For the most current list of supported file types and storage limits, contact Vivlio Health support.
Examples
Node.js
async function listPatientFiles(token, patientId) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/patients/${patientId}/files`,
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.json();
}
async function getFileMetadata(token, patientId, fileId) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/patients/${patientId}/files/${fileId}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
// Use the downloadUrl to fetch the actual file
const fileResponse = await fetch(data.data.downloadUrl);
return fileResponse.blob();
}
async function downloadPatientFile(token, patientId, fileId) {
const fileData = await getFileMetadata(token, patientId, fileId);
// In Node.js, you might save to disk:
// fs.writeFileSync('downloaded_file', fileData);
return fileData;
}Python
import requests
from datetime import datetime
def list_patient_files(token, patient_id, limit=25):
response = requests.get(
f'https://api.vivliohealth.io/ext/latest/patients/{patient_id}/files',
headers={'Authorization': f'Bearer {token}'},
params={'limit': limit}
)
response.raise_for_status()
return response.json()
def get_file_metadata(token, patient_id, file_id):
response = requests.get(
f'https://api.vivliohealth.io/ext/latest/patients/{patient_id}/files/{file_id}',
headers={'Authorization': f'Bearer {token}'}
)
response.raise_for_status()
return response.json()
def download_file(token, patient_id, file_id):
file_data = get_file_metadata(token, patient_id, file_id)
download_url = file_data['data']['downloadUrl']
# Download the actual file
file_response = requests.get(download_url)
file_response.raise_for_status()
return file_response.contentDownload URL Expiration
- Download URLs are temporary and expire after 5 minutes
- Each time you call
GET /patients/{patientId}/files/{fileId}, a new download URL is generated - If a URL expires, request the file again to get a fresh URL — don't cache
downloadUrl
URL Expiration
Always check the downloadUrlExpiresAt timestamp. If expired, make a new GET request to the file endpoint to obtain a fresh download URL.
Pagination
File lists support pagination:
# Get first 25 files
curl "https://api.vivliohealth.io/ext/latest/patients/{patientId}/files?limit=25&offset=0" \
-H "Authorization: Bearer {token}"
# Get next page
curl "https://api.vivliohealth.io/ext/latest/patients/{patientId}/files?limit=25&offset=25" \
-H "Authorization: Bearer {token}"Error Responses
| Status | Code | Description |
|---|---|---|
| 401 | FORBIDDEN | Missing authentication or invalid token |
| 403 | FORBIDDEN | Insufficient scopes (need file:read) |
| 404 | RESOURCE_NOT_FOUND | Patient or file not found |
| 500 | INTERNAL_ERROR | Error retrieving files |
Compliance and Security
HIPAA/Security
All file access is subject to your organization's privacy and security policies. Downloads are logged for audit compliance.
- Files are encrypted at rest
- All access is logged for HIPAA compliance
- Download URLs are time-limited and cannot be shared permanently
- Files can only be accessed by authorized users with proper scopes
