.png)
Nabla Connect is an integration protocol between Nabla and any EHR, that leverages API calls between Nabla's server and your EHR's server. From a high-level standpoint, it enables end users (healthcare providers) to seamlessly initiate Nabla encounters directly from the EHR, carrying over essential context, and facilitating note export back to the EHR.
Specifically, this involves:
Integrated Encounter Creation: EHR provide a URL or button within their UI that initiates a Nabla encounter, automatically linked to the current patient and encounter displayed on their screen.
Contextual Data Sharing: Nabla receives necessary patient context, including patient name, age, gender, and relevant EHR data (Visit Diagnoses etc.).
Simplified Note Export: User-triggered write backs export notes and associated data (visit diagnosis, patient instructions, orders etc.) back into the EHR without the need for manual copy-pasting.
<aside> <img src="/icons/mail_gray.svg" alt="/icons/mail_gray.svg" width="40px" />
Contact us at [email protected] to create your organization
</aside>
Nabla Connect is already available. Some implementation details of the documentation you are reading might change. However, there won't be any differences from a high-level standpoint. Your feedback is valuable and we would love to know if Nabla Connect is well suited for your setup, or if we improve some parts to make it fit better.
The following schema presents the two main steps of the Nabla Connect flow.
From a user perspective the flow looks like this:
Export Note button (that replaces the usual Copy Note one), and all the data we generated (note, visit diagnoses, and more) is sent to their EHR.This is roughly the path the user would follow:
On your side, you will have to:
<baseUrl>/encounter request from your backendNabla will expose APIs that your EHR server has to call to push data to us (referred as "incoming" APIs), and in return, we expect you to expose an endpoint we will call to return some data (referred as "outgoing" APIs). These API calls are authenticated and secured as described further in this document.
Incoming APIs are api calls we expect to receive from you. This typically includes the initial encounter creation call.
<aside> <img src="/icons/link_lightgray.svg" alt="/icons/link_lightgray.svg" width="40px" />
The <baseUrl> for all APIs is [https://<region>.api.nabla.com/v1/connect/server](https://app.nabla.com/api/<REGION>/v1/connect/server)
<region> is us or eu
</aside>
We expect you to authenticate your request with an access token generated by our server. To get this access token, we want you to follow our Server API authentication flow, using OAuth Clients. In short:
<baseUrl>/oauth/token request to us, with a JWT signed with your private keyFor more details, you can refer to the server authentication docs:
Description: This endpoint should be called by your backend upon clicking the button in the encounter chart. You should provide IDs in your system (provider, patient, encounter), and the encounter data. We will send back these IDs during the note export phase.
Upon receiving the request, Nabla will try to match the user corresponding to your provider, create the encounter, and return an URL your front end should navigate to. Navigating to this URL will log in the provider into Nabla automatically, and open the app on this encounter.
<aside> 👤
With the provider_email, Nabla will provision the user if it doesn't already exist.
The request will fail if the external_provider_id of an existing user doesn't match the given provider_email.
</aside>
Method: POST
Path: <baseUrl>/encounter
Request payload:
{
"provider_email": string,
"external_patient_id": string, # external id from your ehr
"external_provider_id": string, # external id from your ehr
"external_encounter_id": string, # external id from your ehr
"encounter_data": {
"patient_name": string,
"patient_dob": string, # YYYY-MM-DD format
"patient_gender": enum, # "FEMALE", "MALE", "OTHER", "UNKNOWN"
"patient_pronouns": enum | null # "HE_HIM", "SHE_HER", "THEY_THEM"
}
}
Response:
{
"encounter_url": string # URL
}
Outgoing APIs are api calls you will receive from us.
We expect you to verify that the request is correctly signed by us.
These APIs typically correspond to when we want to export our generations to you, so that you can store it, and display it in your EHR. This typically includes the note Nabla generates.
You can configure the callback URL (*<callback_url>*) on which you will be called on the Admin page.
You can get the signature secret on the Admin page.
We use an HMAC Signature Verification. HMAC (Hash-based Message Authentication Code) verification is a lightweight but robust way to ensure that outgoing api calls genuinely originate from Nabla and have not been tampered with in transit.
Each callback request to your endpoint includes the following headers:
x-nabla-callback-timestamp: An ISO 8601 timestamp of when the request was generated.x-nabla-callback-signature: One or more HMAC signatures of the request body, generated with a shared secret key.The signature is calculated using the HMAC-SHA256 algorithm based on:
x-nabla-callback-timestamp.These signatures are included in the x-nabla-callback-signature header.
To securely validate a callback on your server, implement the following:
Here's a JavaScript sample code for the signature verification described above:
For more details on HMAC-SHA256 please refer to RFC-2104 and RFC-4231.
All requests Nabla will send to your EHR a callback on a predefined url you provide us. The payload is polymorphic, the schema depends on the type field.
{
"request_uuid": string, # unique uuid to identify the request
"type": "NOTE_EXPORT|PATIENT_INSTRUCTIONS_EXPORT|...", # type
# ...
}
200 for every request we send that you recognize. You must respond with a body containing the same request_uuid as the request:type you don't support, you should respond with 400.401.