SOFT Integration

SOFT Integration lets your EHR open an Invox Genesis consultation for a physician who is already authenticated in your own system, without asking that physician to log in again on the Invox Medical platform.

Your backend requests a short-lived signature for a given physician and consultation, opens Invox Genesis with that signature, and receives the clinical result back when the consultation ends.

When to use it

Use case	Recommended integration
Your physicians already work inside your EHR and you want to embed the Invox Genesis consultation experience	SOFT Integration
You only need to transcribe audio or generate a report from your own recording pipeline	AI Services
You need to manage users, groups or organizations programmatically	Management API

How the flow works

  Your EHR                      Invox Medical                  Physician's browser
     │                                │                                │
 (1) │ POST generate-signature        │                                │
     ├───────────────────────────────►│                                │
     │◄──────── { signature } ────────┤                                │
     │                                │                                │
 (2) │ open /genesis?third-party-signature=<signature>                 │
     ├────────────────────────────────────────────────────────────────►│
     │                                │◄──── records the consultation ─┤
     │                                │                                │
 (3) │◄─ webhook (push) and/or WebSocket (pull) ─┤                     │
     │                                │                                │
 (4) │ GET /soft-integration/{requestId}/result                        │
     ├───────────────────────────────►│                                │
     │◄──────── { result } ───────────┤                                │

Request a signature. Your backend calls Generate signature with the physician's email, your organizationId, your own requestId and the consultation metadata. Invox Medical validates that the physician exists, is enabled and belongs to that organization, and returns a short-lived signature.
Open Invox Genesis. Your front end opens the Invox Genesis URL with the signature attached, in an iframe or in a browser window. The physician sees only the consultation view.
Get notified. When the consultation finishes, you are notified through a webhook, a WebSocket, or both.
Retrieve the result. You fetch the clinical result with Get consultation result, using your own requestId.

If the physician abandons the consultation, you can release the session with Cancel consultation instead of waiting for the signature to expire.

Key concepts

Concept	Description
`signature`	Single-use, short-lived credential that authorizes opening one consultation for one physician. It is not an access token.
`requestId`	Identifier you generate. It correlates the signature, the consultation and the result. Must be unique while the session is alive.
`consultationMetadata`	Context of the consultation. Free-form: send as many fields as you need. It is shown to the physician inside Invox Genesis.
`organizationId`	Your organization in the Invox Medical platform. The physician must belong to it.

Security model

The signature is issued only to a caller whose API Key holds the GENESIS-SOFT-INTEGRATION permission. See Prerequisites.
The physician is validated fail-closed at issue time: if the user does not exist, is disabled, or does not belong to the declared organization, no signature is issued.
The signature has a maximum lifetime of 3 hours and is bound to a single consultation.
The signature never carries clinical data. The clinical result travels only over your signed webhook or over an authenticated request of yours: the WebSocket channel carries just a notice, never the report.
All traffic must use TLS. Requests over plain HTTP are rejected.

Treat the signature as a credential. Do not log it, do not store it, and do not expose it anywhere other than the Invox Genesis URL and the notification WebSocket handshake.

Environments

The production base URL for every REST endpoint in this section is:

https://api-suite.invoxmedical.com

The production URL of the Invox Genesis consultation view is:

https://suite.invoxmedical.com/genesis

Release NotesChangelog

Soft IntegrationPrerequisites