Sribe API: EHR Integration
There are currently three methods of integration that Autoscriber, as described below high-level:
- Embedded Web App:
This option is perfect for EHRs wanting a simple integration with Autoscriber's digital AI scribe and is happy to embed Autoscriber's UI in an iframe within the EHR, with the ability to sync the resultant structured note with the EHR.
- SDK:
This option enables the EHR to have control over their frontend UI, and from there, utilise the Autoscriber Scribe SDK to manage the audio recording and automatically generate the resultant structured note and post it back to the EHR via API.
- Scribe API:
This option is the most flexible of the three options, and provides the EHR with the capability to utilise the backend APIs to generate structured notes from audio that is passed from the EHR. However, this option can be considered the most complex out of the three available as the EHR manages the recording within the EHR and needs to pass audio chunks to Autoscriber via API in real-time.
This article discusses the steps required to set up Option 3.
Table of Contents
Overview
As mentioned above, this option is the most granular option when it comes to integrating Autoscriber into your EHR. By utilising the Scribe API, you can incorporate our scribe solution into your workflow however you please.
This article goes through the steps required to know how to use this API.
Request an API Key
Before you can make requests to the API, you will need to obtain an API key. You can request an API key by emailing autoscriber at integrations@autoscriber.com.
We will provide you with an API key via a secure 1password link.
Call the
scribe
endpoint
Call the below endpoint through a POST
request:
https://io.autoscriber.com/v1/scribe
Headers
The headers are as follows:
api-key
- Type: string
- Value: Your api-key provided in Step 2
Content-Type
- Type: string
- Value:
application/json
Body
The body attributes are as follows:
Name |
Description |
Type |
Required/Optional |
priority | Value between 1-9, you can prioritise certain requests within your bandwidth. | Integer | Optional |
billingReference | This is the value (between 0 and 40 characters) Autoscriber uses to distinguish between EHRs, environments and customers. Therefore, please use the following guidelines: EHR Test Environment: "EHRName_Test" EHR Prod Environment: "EHRName_Prod" Once a customer starts using the integration, please use the following guidelines: "EHRName_CustomerName_Test" or "EHRName_CustomerName_Prod" |
String | Required |
userId | An optional userId that enables the api to personalise the response. Value must between 0 and 40 characters. | String | Optional |
communication | Configuring the communication methods. See attributes below. |
Object | Required |
in | The inputs needed for the API. This is either See the attributes associated to each option below. |
Object | Required |
out | The types of outputs required. See attributes below. |
Object | Required |
The above nested communication
attributes are as follows:
Name |
Description |
Type |
Required/Optional |
method | See SDK & API: Communication Methods. Options include get|socketio|sse|webhook |
Boolean | Required |
webhook | Required if method==webhook See attributes below. |
Object | Optional |
The above nested webhook
attributes are as follows:
Name |
Description |
Type |
Required/Optional |
url | The url Autoscriber should call | String | Required |
headers | Optional headers Autoscriber will use when posting to your url (e.g. auth headers) | String | Optional |
The above nested in
attributes are as follows:
Name |
Description |
Type |
Required/Optional |
type | The type of input, either conversation or text . |
String | Required |
language | The language of the input. Must be one of the supported languages en|nl|de . |
String | Required |
audioType | The format of the audio. Options include mp3 , webm , wav , flac , ogg , m4a . Required if type includes audio . |
String | Required if type==conversation |
text | Required if type== The text that needs to be summarised |
String | Required if type==text |
The above nested out
attributes are as follows:
Name |
Description |
Type |
Required/Optional |
type |
See here for Dutch templates See here for English templates |
String | Optional |
toggleCodes | To indicate if you want to receive medical coding with the note. | Boolean | Optional |
coding_systems | Whether SNOMED_CT or ICD10 medical codes are generated. If coding is needed, then either "SNOMED_CT" or "ICD10" must be included |
String | If If |
Example request body
A simple example using text as input can be seen here: https://wtf.autoscriber.com/article/314-scribe-api-text-example
An example using audio can be seen below:
Here is an example of the request body:
{ "priority": 1, "billingReference": "EHRName_Test", "userId": "user123", "communication": [{"method":"SSE"}], "in": [{"type":"conversation", "language":"en", "audioType":"mp3"}], "out": [{"type":"standard_en", "togglecodes":true, "coding_systems":SNOMED_CT}] }
JSON Example Response:
{ "id": "<ID>", "location": "https://io.autoscriber.com/v1/scribe/<ID>", "chunkLocation": "https://io.autoscriber.com/v1/scribe/<ID>" }
JSON Posting chunks to chunkLocation
:
{ "index": 0, "base64": "<STRING>", "final": false }
Since this example has the communication method SSE
, once you have sent the "final": true
audio chunk, you will receive the resultant summary and transcript via the connection established with the location
.
To see what happens for other communication methods, you go here: SDK & API: Communication Methods
Receive the Summary and Transcript
In response to posting the audio chunks to the chunklocation
, the summary and transcript will be sent to you via the method stipulated in the original request (see here for the description in this article, and here to get an overview of the SDK & API: Communication Methods).
Here is an example of the resultant summary that you will receive:
{ "standard_en": { "final": true, "data": [ { "items": [ { "sentences": [], "text": "Strong heachaches since 5 days" } ], "section": "Subjectief" }, { "items": [ { "sentences": [], "text": "Refer to neurologist" } ], "section": "Plan" } ], } }
The template and associated headings will be dependant on what template type
was included in the request.
Types with episodes
The following templates will produce multiple episodes, depending on what was discussed during the consultation:
- soap_episodes_en
- soap_episodes_nl
If one of these were included in the request, the following is an example of the output:
{ "soap_nl": { "final": true, "data": [{ "episode": "Headache", "note": [ { "items": [ { "sentences": [], "text": "Strong heachaches since 5 days" } ], "section": "Subjectief" }, { "items": [ { "sentences": [], "text": "Refer to neurologist" } ], "section": "Plan" } ] }] }, }
Download our example app
To see an example of our application, it is recommended to download our example javascript app, which allows you to try out the scribe API (by streaming audio from your microphone).
This can be accessed via our Github page, written in svelte
, which implements the API. We highly recommend you to get started there, especially if you know your way around javascript.