Skip to content

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 ​

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

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

http
GET /ext/latest/patients/{patientId}/files/{fileId}
Authorization: Bearer {token}

Response:

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

FieldTypeDescription
fileIdstringSystem-generated file UUID
fileNamestringOriginal file name
documentTitlestringDocument title (falls back to fileName if not set)
documentAuthorstringDocument author, when known
dateOfServicestringDate of service the document relates to (YYYY-MM-DD); null when unknown
facilitystringFacility the file was retrieved from
parentFacilitystringParent health system/facility; null when unknown
fileStatusstringProcessing status of the file
fileSizenumberFile size in bytes
createdAtstringDate the file record was created (YYYY-MM-DD)
updatedAtstringLast-updated timestamp (ISO 8601)
s3KeystringInternal storage key — not directly downloadable; use downloadUrl instead
downloadUrlstringPre-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.
downloadUrlExpiresAtstringdownloadUrl 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 ​

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

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

Download 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:

bash
# 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 ​

StatusCodeDescription
401FORBIDDENMissing authentication or invalid token
403FORBIDDENInsufficient scopes (need file:read)
404RESOURCE_NOT_FOUNDPatient or file not found
500INTERNAL_ERRORError 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

Vivlio Health API Documentation