Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This API uses HL7's SMART App Launch Framework to display the Dragon Copilot user interface in your EHR.
For more information on SMART App Launch, see the HL7 documentation, https://hl7.org/fhir/smart-app-launch/app-launch.html#launch-app-ehr-launch (section 2.1.7, "Launch App: EHR Launch").
Base URL
HTTP requests to the Dragon Copilot integration service all use the following base URL:
https://ehr-integration.copilot.dragon.com
Launch the API
To start the SMART App Launch process on FHIR, send a GET request to the following endpoint:
/app/{ehr}/launch?iss={issuer}&launch={launch_identifier}
SMART App Launch parameters
| Type | Name | Required | Description | Schema |
|---|---|---|---|---|
| URL | ehr |
Yes | The name of the EHR system making the call. This value is agreed with Microsoft as the identifier of your EHR app when you onboard to Dragon Copilot. Once agreed, Microsoft needs to configure this value before it can be used. | String |
| Query | issuer |
Yes | The EHR's FHIR endpoint, which is used to obtain additional details about the EHR system. | String |
| Query | launch_identifier |
Yes | A unique identifier for this specific launch event. | String |
Callback API
To complete the SMART App Launch process, send a GET request to the callback endpoint:
/app/{ehr}/callback?code={code}&state={state}&error={error}&{errorDescription}
Callback API parameters
| Type | Name | Required | Description | Schema |
|---|---|---|---|---|
| URL | ehr |
Yes | The EHR system making the call | String |
| Query | code |
Yes | The authorization code generated by EHR authorization server, which will be exchanged for the access token. The authorization code needs to expire shortly after it is issued to mitigate the risk of leaks. | String |
| Query | state |
Yes | An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHALL be used for preventing cross-site request forgery or session fixation attacks. The app SHALL use an unpredictable value for the state parameter with at least 122 bits of entropy (e.g., a properly configured random uuid is suitable). | String |
| Query | error |
No | A failure or issue on EHR side that prevents the launch request from being processed successfully. | String |
| Query | errorDescription |
No | A more detailed explanation of the specific error that occurred, to help with debugging. | String |
Context tokens
On completion of the SMART App Launch process, your EHR needs to provide the following context information:
| Name | Required | Description |
|---|---|---|
partnerId |
Yes | The Microsoft-defined identifier of the product for which the session is being created. |
orgId |
Yes | The Microsoft-defined identifier of the customer for whom the session is being created. |
ambientSessionId |
Yes | Deprecated; use correlationId instead. The partner-defined identifier of the session being created. |
correlationId |
Yes | The globally unique identifier for a session that's specific to the partner system and helps track and associate recordings with the corresponding encounter. The correlation ID must be associated with every recording of a session and is also associated with the AI output. The identifier must have the following characteristics:
|
emrId |
Yes | The user ID as defined by your EHR. |
productId |
Yes | The Microsoft-defined identifier of the product for which the session is being created. |
sectionName |
No | The document section that the user is viewing. |
documentSections |
No | The document sections that had data, as a comma-separated list. |
documentVersion |
No | The version of the document that the user is viewing. |
launchType |
No | The Dragon Coilot functionality that you want to display in your EHR. Possible values:summaryFeedback - displays a UI where the user can provide feedback on the note created by Dragon Copilot from ambient recordings. This is the default if no value is provided. The user can select one of the following options:Looks right Needs improvement Offensive, inappropriate or biased The user can also type free text comments. copilot - redirects to the Dragon Copilot web app. |
Error codes
Dragon Copilot Embedded for Desktop returns the following errors in response to failure scenarios:
SMART App Launch configuration errors
| Status code | Error code | Name | Description |
|---|---|---|---|
| 400 | 7 | LaunchParametersMissing |
The iss or launch parameter is missing. |
| 500 | 11 | TokenEndpointMissing |
The issuer's token endpoint is missing. |
| 400 | 26 | EhrIdMissing |
The EHR ID was not provided in the SMART context. |
| 500 | 27 | EhrContextInvalid |
The SMART context is invalid. Validate the context parameters. |
| 400 | 30 | InvalidIssuer |
The issuer is invalid. Verify the issuer's ID. |
Dragon Copilot integration service errors
| Status code | Error code | Name | Description |
|---|---|---|---|
| 500 | 1 | Generic |
A generic error on the backend side. This requires further investigation by the backend team. |
| 500 | 8 | SmartConfigFetchError |
An error occurred getting the SMART configuration. |
| 400 | 9 | CallbackParametersMissing |
Required callback parameters are missing. |
| 500 | 10 | CodeVerifierMissing |
The code verifier is missing. |
| 500 | 12 | AccessTokenFetchError |
An error occurred getting the access token. |
| 500 | 13 | IdTokenMissing |
The ID token is missing from the authorization response. |
| 500 | 14 | IdTokenInvalid |
The ID token is invalid. |
| 400 | 25 | CallbackErrorFromEhr |
An error during the callback from the EHR. |