Changelog
v1.5.1 — Patient Files Response Cleanup
Release Date: 2026-10-07
Impact: Minor - backward compatible enhancement
Improvements
GET /patients/{patientId}/filesandGET /patients/{patientId}/files/{fileId}no longer return undocumented internal fields:dateOfServiceDate,repositoryUniqueId,workflowId,metadataFileName,transactionType,downloadOnly,particleQueryId,downloadAttempts, andregistryObjectServiceStartTime. Use the documented fields instead.parentFacilityis nownullwhen no parent facility is known, instead ofUnknown FacilityorParticle 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}/filesandGET /patients/{patientId}/files/{fileId}now returndateOfService(YYYY-MM-DD, ornullwhen unknown).
Bug Fixes
- Paging of
GET /patients/{patientId}/filesis now deterministic, withfileIdas 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, sototalcan 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
dateOfService2field on both the files list and single-file endpoints now carries the date of service asYYYY-MM-DD(previously a full timestamp, with fallbacks derived from file metadata and file names) and isnullwhen no date of service is recorded. This field is undocumented and should not be relied on; usedateOfServiceinstead. - Facility information (
parentFacility,facilityState) onGET /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 stringerrorfield instead of the documented object. Validation failures carryVALIDATION_ERROR; missing-resource responses carryRESOURCE_NOT_FOUND; method-not-allowed responses carryMETHOD_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.codeanderror.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
reasonsForReferralarray 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
groupByFileIdhelper
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
queryIdfield 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.mdfor 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=truequery 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=truequery 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
includeFileMetadataomitted orfalse, all three fields absent from response
Breaking Changes
fileNameno longer included in record responses by default - pass?includeFileMetadata=trueto 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 nestedreasonsForVisitarray 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
fileNamefield (source document file name ornull)
Improvements
- problemList and planOfCare support
startDatefiltering; careTeam supports bothstartDateandendDate
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
GET/PUT /client- view and update your own organization info → Client Self-Service
Users
- Full CRUD for users; creates a Cognito account on
POST→ Users
Patients
- Full CRUD plus
POST /patients/batchfor upsert of up to 100 patients → Patients
Providers
- Full CRUD with
listModefilter (active/all) → Providers
Appointments
- Full CRUD plus
POST /appointments/batchfor 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}/filesandGET /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
requestIdfrom error responses - Feature Requests — Submit requests through your account dashboard
- Documentation — Check the guide and API reference for detailed endpoint documentation
