Changelog & Upgrades

Overview

Updates to the Invox Medical API — including new features, fields, or endpoints — are released under a new dated version to ensure stability and predictability. This means your integration won't be affected by these changes unless you explicitly opt into the newer version.

Version History

PENDING-PROD-DATE: permission enforcement (all API versions)

AI Services Updates

• Translation: Translate transcription and Translate clinical note require the permission TRANSLATE. Without it they return 403 with errorType invalidPermission.
• Document deletion: Delete document requires the permission GENERATE-REPORT. Without it it returns 403 with errorType invalidPermission.
• Behavior change: DELETE /v1/delete-document now returns 404 for documents not created with the same API Key (or, for Suite sessions, by the same user).
• Rotated credentials: after you rotate a credential, documents created with the previous API Key can no longer be deleted.
• A malformed JSON body in /v1/delete-document and /v1/translate-clinical-note now returns 400 inconsistentInput (previously 500).
• Granting or removing a permission can take up to 2 hours to take effect, because access tokens already issued keep the permissions they had when they were created.

Version 2026-11-01

AI Services Updates

Generate clinical note: template errors

• Without the version header or with 2026-11-01: a template that used to be rejected with 500 (errorGeneratingMedicalReport) because of a structural defect, such as a missing template_name or template_description, a value that is not a string, or a null field, now returns 400 with errorType invalidTemplateSchema. The message has the format Template schema validation failed: <path>: <rule> and never includes the values you sent. A missing transcription returns 400 (invalidTranscription).
• With 2026-10-01 or earlier: the 500 is kept. Pin the header to 2026-10-01 to keep it.
• The templates and the 400 errors that already worked are unchanged, with the same errorType and message.

Published contracts

• The API publishes the template and the report as versioned JSON Schemas, public and without authentication: GET <baseUrl>/api/v1/contracts/template-definition/v1 and GET <baseUrl>/api/v1/contracts/report-output/v1. They are immutable: a change is published as v2.
• The unversioned JSON Schema in S3 is legacy and is no longer updated.
• The documentation fixes the 400 error type of an invalid field type to its real value, fieldsWithInvalidType.

Other endpoints

• All AI Services and SOFT Integration endpoints available in 2026-10-01 also accept 2026-11-01, with no changes in their behaviour.
• The legacy /api/v1/generate-report endpoint does not support 2026-11-01.

Version 2026-10-01

AI Services Updates

Medical Text Formatter: new contract

The Medical Text Formatter endpoint (POST /api/v1/medical-text-formatter) introduces a new contract:

• New request fields:
  • formatting_level (optional, "low" | "medium" | "high", default "medium"): sets the maximum degree of intervention, from a deterministic cleanup (low) to AI-assisted reorganization (medium) or style editing (high).
  • immutable_words (optional, string[], default []): words or expressions that must be kept exactly as written (same case and accents) in the formatted text.
• text limits: text is required and must be between 1 and 50000 characters.
• Fields without effect: language and preserve_case are still accepted but ignored. The language of the text is always detected automatically.
• Response changes: the message field is removed and a new timestamp field (ISO 8601, UTC) is added. formatted_text and request_id are kept.
• Error responses: errors now always return a { message, errorType } body with status 400 (invalidRequestBody), 500 (errorGeneratingMedicalReport) or 503 (serviceTemporarilyUnavailable). The previous 422 response is no longer returned.

Other endpoints

• All AI Services and SOFT Integration endpoints available in 2026-08-01 also accept 2026-10-01, with no changes in their behaviour.
• The legacy /api/v1/generate-report endpoint does not support 2026-10-01. It remains available only in 2025-10-01 and 2025-11-01. Use Generate Clinical Note instead.

Management API Updates

New endpoints

• Disable user (PATCH /users/:id/disable): disables a user who belongs only to your organization, so they can no longer sign in.
• Enable user (PATCH /users/:id/enable): enables a disabled user who belongs only to your organization, including users blocked after too many failed login attempts.

Behaviour change

• Invite user: an Organization Admin can no longer invite users with the ORGANIZATION_OWNER role. The request now returns 403 with errorType: "notAllowedResource", the same response that Edit user already returns for this rule. Only an Organization Owner can invite Organization Owners.

Search events: pagination and new filters

Search events (POST /events/search) can now export every event of an organization, page by page:

• Pagination: there is no longer a maximum number of events per search. The new optional pageSize field (1 to 5000, default 500) sets the events per page, and the response includes a new pagination object (pageSize, count, hasMore, nextCursor). Send nextCursor as cursor to get the next page; hasMore: false means there are no more events.
• New optional filters: organizationId (any organization in which you are Owner or Admin; by default, the selected one), eventName and eventType (a single value or an array).
• userId is optional: when omitted, the events of every user in the organization are returned.
• More event data: each event now includes eventType, section and resource. In CSV output these columns, and metadata, are added after the existing ones, which keep their order.
• Default page size: requests without limit or pageSize now return up to 500 events instead of 100. limit is still accepted as a deprecated alias of pageSize, now from 1 to 5000.
• Validation: a startTimestamp greater than endTimestamp now returns 400 (invalidTimestampRange) instead of an empty list. New errorType values: invalidPageSize, invalidCursor, invalidUserId, invalidOrganizationId, invalidEventName and invalidEventType.
• Errors: a search that cannot be resolved in time returns 504 (searchQueryTimeout), and a failed search returns 500. Previously both cases could return 200 with an empty list.

Fixes (same status codes and response structure)

• Select account: sending a selectedAccount that is not one of your organizations no longer clears your current selection.
• Group list: requests without limit now return the groups of the organization instead of an empty list.
• Invite user: a groupId that does not belong to your organization is ignored, and the user is created without a group. When the email already had a platform account, the id field now contains the user identifier.
• Delete group: the users of a deleted group are left without a group (groupId: "NOT-DEFINED") instead of pointing to the deleted group.
• Delete user: deleting a user who belongs to several organizations now only removes them from your organization.
• Requests with a body that is not valid JSON still return 400, now with a JSON body instead of an HTML page.

Documentation

• All Management API pages now document the complete output of each endpoint: response fields, 401 and 403 bodies, and every errorType and errorMessage value. See Common responses.

Version 2026-08-01

SOFT Integration

New integration model

• Introduced SOFT Integration, which lets your EHR open an Invox Genesis consultation for a physician without the physician logging in, and retrieve the resulting clinical note.
• New endpoint Generate signature (POST /api/v1/generate-soft-integration-signature) to authorize a single consultation for a single physician.
• New endpoint Get consultation result (GET /api/v1/soft-integration/{requestId}/result) to retrieve the clinical note once the consultation has finished.
• New endpoint Cancel consultation (DELETE /api/v1/soft-integration/{requestId}) to release a physician whose session was abandoned.
• SOFT Integration consultations are notified through the existing OnMedicalReportFinished webhook event, marked with origin: "SOFT_INTEGRATION" and carrying the optional consultationMetadata. There is also a WebSocket channel for the browser.
• Requires an API Key holding the new GENESIS-SOFT-INTEGRATION permission.

AI Services Updates

Generate Clinical Note Enhancements

• Added a new generationMetadata field to the Generate Clinical Note response. It provides detailed information about the generation outcome, including whether the result was partial, the number of failed fields, per-field status, and a recommendation for the client.
• Supports partial responses: when one or more fields fail to generate, the response now returns the successfully generated fields along with failedFields (each with a reasonCode and retryable flag) and a recommendation (e.g. RETRY_RECOMMENDED).

Version 2026-03-01

New Features

Updates

• All previous features from version 2025-11-01 are included and maintained.
• Addeed new endpoints for generating pre-signed URLs for document uploads and deleting uploaded documents in the context of clinical note generation.
• Added Consultation Summary Generation endpoint to generate summaries based on audio transcriptions.
• Added IM Tools endpoints
• Added support for generating clinical note in Euskera, Galician and Valencian.

Webhooks

• Added Webhooks documentation section with full reference for all available webhook events, including credentials, signature verification algorithm, and implementation examples in TypeScript, C#, Java, and Python.
• Supported events: OnTranscriptionFinished, OnMedicalReportFinished, OnInvoxAuraTranscriptionFinished, OnInvoxAuraClinicalNoteCreated, OnInvoxAuraClinicalNoteFinished, OnInvoxAuraAudioCreated, and OnAlertTriggered.

Version 2025-11-01

AI Services Updates

Streaming Transcription Enhancements

• Updated input data contract: we introduce the session concept
• Removed callbackUrl field as mandatory when opening the web socket
• Added a new kind of message type: END_TRANSCRIPTION
• Clarified the usage of isTranscriptionCompleted field

For more details, check the Streaming Transcription Guide and the Get Transcription endpoint.

New Translation Endpoints

• Added endpoint for translating transcriptions: We have added a new endpoint that allows translating transcriptions generated by our AI services. Check the Translate Transcription endpoint for more details.
• Added endpoint for translating clinical notes: We have added a new endpoint that allows translating clinical notes generated by our AI services. Check the Translate Clinical Note endpoint for more details.

Changed Generate Report Endpoint

• New endpoint for generating medical reports: We have renamed the existing generate-report endpoint to generate-clinical-note to better reflect its purpose. Check the Generate Clinical Note endpoint for more details.

Management API Updates

• Select account after successful authentication: After successfully authenticating, users can now select the desired account to work with, enhancing flexibility for multi-account users. For more details, refer to the Select account.
• Search events: allow us get events or actions performed by users in the platform. Check the Search Events endpoint for more details.
• Login endpoint: Output contracts have been updated: added accounts field to list all accounts associated with the authenticated user, added userId field to identify the user, added fullName field to provide the user's full name.

Version 2025-10-01

Initial Release

• First version of the API
• Core AI Services functionality
• Management API endpoints
• Authentication system

Upgrade Guide

Migrating to Version 2026-11-01

There is nothing to migrate if you already send X-Invox-Medical-Api-Version: 2026-10-01 or an earlier version: your integration behaves exactly as before. The rest of the endpoints behave exactly as in 2026-10-01.

Generate clinical note: template errors

1. What changes: only the templates that used to be rejected with 500 (errorGeneratingMedicalReport) because of a structural defect, such as a missing template_name or template_description, a value that is not a string, or a null field. They now return 400 with errorType invalidTemplateSchema and a message with the format Template schema validation failed: <path>: <rule>. A missing transcription returns 400 (invalidTranscription).
2. What does not change: the templates that were accepted, and every 400 that already existed, keep the same errorType and message.
3. Version header: requests without the header use 2026-11-01. If you handle the 500 of an invalid template and are not ready to handle the 400, send X-Invox-Medical-Api-Version: 2026-10-01.
4. Published contracts: the template and the report are available as versioned JSON Schemas at <baseUrl>/api/v1/contracts/template-definition/v1 and <baseUrl>/api/v1/contracts/report-output/v1. They are public and do not need authentication.

Migrating to Version 2026-10-01

The only breaking change affects the Medical Text Formatter endpoint. The rest of the endpoints behave exactly as in 2026-08-01.

Medical Text Formatter Updates

1. Request: stop sending language and preserve_case, since they no longer have any effect. Use the new optional formatting_level and immutable_words fields if you need them.
2. Response: remove any dependency on the message field. Use the new timestamp field if you need the date of the response.
3. Errors: handle 400, 500 and 503 responses with the { message, errorType } body instead of the previous 422 response. 503 responses can be retried.
4. Version header: if you are not ready to upgrade, send X-Invox-Medical-Api-Version: 2026-08-01. Requests without the header receive the 2026-10-01 contract.

Migrating to Version 2025-11-01

If you're currently using streaming transcription services, please review the following breaking changes:

Streaming Transcription Updates

1. Session Concept: Update your integration to handle the new session-based workflow
2. CallbackUrl Changes: The callbackUrl field is no longer mandatory when opening WebSocket connections
3. New Message Types: Handle the new END_TRANSCRIPTION message type in your WebSocket message handlers
4. isTranscriptionCompleted Field: Update your logic to check for the isTranscriptionCompleted field to determine when transcription is complete and retrieve the transcription using the Get Transcription endpoint.

Recommended Actions

• Review your WebSocket implementation
• Update message type handlers
• Test with the new session workflow
• Update error handling for the new message structure

Targeting a specific version

Default API Version

If we don't specify a version when making API requests, the system will automatically use the latest stable version available. This ensures that we always benefit from the most recent features and improvements without needing to adjust our integration.

Specifying a Version

To set the API version on a specific request, you can add a specific header named X-Invox-Medical-Api-Version with the value of the version you are targeting:

X-Invox-Medical-Api-Version: 2026-10-01

This approach allows us to maintain compatibility with a specific version of the API while still having the flexibility to upgrade when we're ready.