Skip to content

Changelog ​


v1.5.1 — Patient Files Response Cleanup ​

Release Date: 2026-10-07
Impact: Minor - backward compatible enhancement

Improvements ​

  • GET /patients/{patientId}/files and GET /patients/{patientId}/files/{fileId} no longer return undocumented internal fields: dateOfServiceDate, repositoryUniqueId, workflowId, metadataFileName, transactionType, downloadOnly, particleQueryId, downloadAttempts, and registryObjectServiceStartTime. Use the documented fields instead.
  • parentFacility is now null when no parent facility is known, instead of Unknown Facility or Particle Health.

Supported until: 2027-03-10


v1.5.0 — Document consistency ​

Release Date: 2026-09-29
Impact: Major - stable release

Improvements ​

  • Updated documentation with Sandbox patient information for easier setup

Supported until: 2027-03-10


v1.4.2 — Patient Files Performance & Date of Service ​

Release Date: 2026-10-07
Impact: Major - stable release

Patient Files ​

  • GET /patients/{patientId}/files and GET /patients/{patientId}/files/{fileId} now return dateOfService (YYYY-MM-DD, or null when unknown).

Bug Fixes ​

  • Paging of GET /patients/{patientId}/files is now deterministic, with fileId as a final tie-breaker. Previously, files with equal sort values could repeat or be skipped across pages.
  • Files known to be duplicates of another file are no longer returned by GET /patients/{patientId}/files, so total can be lower than before.

Improvements ​

  • The patient files list query was restructured for performance.
  • The files list is ordered by date of service, and files with no date of service now sort after files that have one.
  • The undocumented dateOfService2 field on both the files list and single-file endpoints now carries the date of service as YYYY-MM-DD (previously a full timestamp, with fallbacks derived from file metadata and file names) and is null when no date of service is recorded. This field is undocumented and should not be relied on; use dateOfService instead.
  • Facility information (parentFacility, facilityState) on GET /patients/{patientId}/files/{fileId} is now resolved the same way as on the files list endpoint.

Supported until: 2027-03-10


v1.4.1 — Consistent 4xx Error Envelope ​

Release Date: 2026-09-21
Impact: Major - stable release

Bug Fixes ​

  • All 4xx responses from the external API now return the documented error envelope: {"error":{"code","message","requestId"}}. Previously, validation errors returned raw Joi detail arrays, missing-resource errors returned bare strings, and 405s returned a string error field instead of the documented object. Validation failures carry VALIDATION_ERROR; missing-resource responses carry RESOURCE_NOT_FOUND; method-not-allowed responses carry METHOD_NOT_ALLOWED. This affects every resource endpoint (patients, appointments, medical records, providers, users, files, contributions).

Breaking Changes ​

  • Response shape change for all 4xx errors on all external API resource endpoints. Clients parsing raw strings or non-envelope objects from error responses must update to read error.code and error.message.

Supported until: 2027-03-10


v1.4.0 — Encounter Reasons for Referral ​

Release Date: 2026-09-10
Impact: Major - stable release

Providers ​

  • Encounters endpoint now includes reasonsForReferral array on each encounter, containing referral details: referring provider, specialty, referred-to provider, referral date, diagnoses, status, and notes

Improvements ​

  • Internal refactor of encounter enrichment to use shared groupByFileId helper

Supported until: 2027-03-10


v1.3.0 — Patient Alt Names & Addresses ​

Release Date: 2026-08-28
Impact: Major - stable release

General ​

  • Allow patients to have alt names such as Maiden, First, Last, and Middle

Improvements ​

  • Addresses can be set as active or previous by using the 'current' key in the address object

Supported until: 2026-12-31


v1.2.0 — Contributions and Documentation Updates ​

Release Date: 2026-08-17
Impact: Major - stable release

Medical Records ​

  • Optional queryId field links a contribution to one of your own organization's outstanding record-retrieval requests, marked fulfilled once the upload completes (separate, narrower use case from the main network-contribution purpose).

General ​

  • New Endpoint: POST /patients/{patientId}/contributions - Upload a document for a patient so it can be contributed back to the health information network when queried. Returns a pre-signed, time-limited upload URL rather than accepting file bytes directly.
  • New Endpoint: GET /patients/{patientId}/contributions - List contributions for a patient. Supports pagination.
  • New Endpoint: GET /patients/{patientId}/contributions/{contributionId} - Check the status of a contribution.
  • New scopes: contribution:read, contribution:write

Improvements ​

  • API Keys documentation moved from Partners endpoint overview to dedicated API Keys page under collapsible Partners section
  • API Keys page now includes comprehensive documentation: CRUD operations, field reference, usage examples (Node.js & Python), best practices, and error responses
  • Partners sidebar now supports collapsible structure matching Medical Records pattern for improved navigation
  • New Webhook documentation page added - See /guide/webhooks.md for webhook setup, event types, and delivery guarantees

Supported until: 2026-12-31


v1.1.0 — History General & Metadata Control ​

Release Date: 2026-07-31
Impact: Major - stable release

Medical Records ​

  • New Endpoint: GET /patients/{patientId}/records/historyGeneral - Retrieve general medical history questionnaire responses and history items that don't fit into specific categories. Supports pagination and date filtering.
  • All medical record endpoints now support optional ?includeFileMetadata=true query parameter
  • Applies to all 13 medical record endpoints: allergies, careTeam, encounters, familyHistory, historyGeneral, immunizations, labs, medications, notes, planOfCare, problemList, procedures, socialHistory, vitals

General ​

  • When includeFileMetadata=true, three fields from source document are attached: fileName, parentFacility, transactionDate
  • When parameter omitted or false (default), metadata fields absent from response for leaner payloads
  • History General moved from Coming Soon to Active Endpoints

Improvements ​

  • Medical Records guide updated with new filtering parameter table entry for includeFileMetadata
  • Example section comparing responses with and without the flag
  • Updated field reference tables marking metadata fields as conditional

Supported until: 2026-12-31


v1.0.2 — File Metadata Opt-In ​

Release Date: 2026-07-31
Impact: Major - stable release

Medical Records ​

  • Optional ?includeFileMetadata=true query parameter on all medical record endpoints
  • When includeFileMetadata=true, three fields added to each record: fileName (source document file name), parentFacility (facility that submitted file), transactionDate (date file received)
  • Applies to all 14 record types

General ​

  • When includeFileMetadata omitted or false, all three fields absent from response

Breaking Changes ​

  • fileName no longer included in record responses by default - pass ?includeFileMetadata=true to receive it

Supported until: 2026-12-31


v1.0.1 — Encounters with Reason for Visit ​

Release Date: 2026-07-17
Impact: Major - stable release

Base Path: /ext/latest/

Medical Records ​

  • Encounters endpoint (GET /patients/{id}/records/encounters) now includes nested reasonsForVisit array per encounter with fields: id, reason, comment, onsetDate, encounterDate, referral
  • Empty array for encounters without reasons (LEFT JOIN semantics)
  • Medical Records endpoints (careTeam, problemList, planOfCare) now fully available (previously Coming Soon)
  • All medical record responses now include fileName field (source document file name or null)

Improvements ​

  • problemList and planOfCare support startDate filtering; careTeam supports both startDate and endDate

Supported until: 2026-12-31


v1.0.0 — Initial Release ​

Release Date: 2026-07-18
Impact: Legacy - deprecated

Base Path: /ext/latest/

Authentication ​

  • OAuth 2.0 Client Credentials flow → OAuth
  • Partner and Client token types with distinct access levels → Authentication

Partner Management ​

  • Client CRUD (GET/POST/PUT/DELETE /partners/clients) → Partners
  • API Key CRUD (GET/POST/PUT/DELETE /partners/apiKeys) → Partners

Client Self-Service ​

Users ​

  • Full CRUD for users; creates a Cognito account on POST → Users

Patients ​

  • Full CRUD plus POST /patients/batch for upsert of up to 100 patients → Patients

Providers ​

  • Full CRUD with listMode filter (active / all) → Providers

Appointments ​

  • Full CRUD plus POST /appointments/batch for upsert of up to 100 appointments → Appointments
  • HIE auto-query support on appointment creation → HIE Auto-Query

Medical Records ​

  • Medical Records read-only endpoints (GET /patients/{id}/records/{type}) supporting: medications, allergies, encounters, notes, vitals, procedures, socialHistory, familyHistory, labs, immunizations, careTeam, problemList, planOfCare → Medical Records

Patient Files ​

  • Patient Files endpoints (GET /patients/{id}/files and GET /patients/{id}/files/{fileId}) → Patient Files

Improvements ​

  • Full FHIR R4 compliance for medical records
  • Comprehensive OpenAPI specification
  • RFC 7807 Problem Details for error responses

Breaking Changes ​

  • All endpoints now require OAuth 2.0 bearer tokens (breaking from v0.x)
  • Removed deprecated sessionToken authentication method
  • Error response format changed to RFC 7807 Problem Details

Supported until: 2026-12-31

Migration Guide: /guide/migration-v1


Getting Help ​

  • API Issues — Contact support with your requestId from error responses
  • Feature Requests — Submit requests through your account dashboard
  • Documentation — Check the guide and API reference for detailed endpoint documentation

Vivlio Health API Documentation