Getting started

Learn how to integrate Attendi into your application. We recommend using the Attendi Microphone.

Attendi Microphone

We provide client libraries and SDKs for web and native platforms, allowing for simple and fast integration of Attendi into your system. For speech-to-text, the central component is the Attendi Microphone. This component handles recording audio in the correct format and communicating with our backend APIs, and implements UI/UX best practices for recording audio. Using the client libraries, you will always have access to the latest features. The appearance of the Attendi Microphone is highly customizable. Styles such as colors, fonts, size and shape can be changed, so that the component integrates seamlessly with the rest of your application.

The web client library exposes webcomponents, which work with any of your favorite front-end frameworks. To use it:

• Install the Attendi Speech Service package using a package manager, such as npm or yarn. The package @attendi/speech-service is available on our private package registry. Access to the registry is available exclusively for our partners.
• After installation, using the component is as simple as importing the library and using the custom HTML tag <attendi-microphone></attendi-microphone> somewhere in your web application.
• More detailed usage instructions are available in the package README.

As a partner integrating the Attendi Speech Service package into your application, you will also receive access to the code of the component. Our aim here is to be transparent about the code that you are incorporating into your application, ensuring that you have a clear understanding of it.

API Documentation

Our backend APIs are divided into two categories: management and feature APIs. If you are using the Attendi Microphone, you will only need to use the management APIs to incorporate Attendi into your system.

Authentication

We use API keys for authentication through a custom HTTP header. To authenticate your request, include your API key in the x-API-key header.

We use two types of API keys: secret keys and customer keys. Each type has its own prefix, making them easy to distinguish.

• Secret keys: These keys should be treated as highly confidential and should never be shared in publicly accessible areas. They should be used with Management APIs and should be handled with the same level of care as a password.
• Customer keys: These keys are used to identify your tenant and the specific customer using Attendi. Unlike secret keys, customer keys are not considered secret and can be used safely in your frontend. They should be used for Feature APIs.

Key type	Prefix	Usage
Secret	sk_	Management APIs
Customer	ck_	Feature APIs

Security

We use end-to-end TLS/SSL encryption to encrypt and transmit of data to our backend securely. All API requests must be made over HTTPS. Requests made over plain HTTP will fail, as will API requests without authentication.

Cross-Origin requests are only allowed for feature APIs when using your customer key from a frontend application.

Management APIs

After receiving your secret key, you need to create customers. Each customer will be assigned a unique customer API key, which should be used to integrate Attendi into your system and allows to identify your customer.

You can view the complete documentation detailing all Management API endpoints here.

Customers and Units

A customer refers to a health care organization, and a unit refers to a team or location within that health care organization. This separation allows you to track usage of different teams, so that you are aware of varying levels of activity and adoption of Attendi.

For both customers and units, there are several endpoints for creating, updating and retrieving them. You can create the customer or unit with the ID that you use in your internal systems. To synchronize changes in your internal systems with ours, a customer or unit can be updated using a PUT or a PATCH request. If you're using the PUT endpoint, make sure to send the complete request object. If you only wish to update a single field, you can use the PATCH endpoint.

API keys

If you want to revoke a customer key and create a new one, you can use the roll endpoint. This endpoints accepts a request body parameter indicating the amount of seconds in which the key should expire. Once you have rolled your customer key and replaced it in your frontend where necessary, you can delete the key completely using the DELETE endpoint.

Feature APIs

If you do not wish to integrate Attendi into your system using the Attendi Microphone, it is also possible to use the Feature APIs directly.

Transcribe

The transcribe endpoint allows you to get a transcription of an audio file. The audio should be a base64 string and should meet the following specifications:

• Single (mono) channel recording
• 16 kHz sampling rate
• 16-bit audio recording

If your audio file does not meet these requirements, it cannot be processed.

In addition to the audio file, you also need to provide the following parameters:

• user_id: A unique identifier for the user who recorded the audio. This identifier can be the same as the ID used in your system. We do not store any personal data, but use this ID to track usage and to trace any problems.
• unit_id: An identifier for the unit of usage. Based on this identifier received in the request, we can link and track the usage per team. This unit_id should correspond to the unit identifier provided to us via the management API. It is required to send the user's unit ID in the request to track usage on a unit level.
• report_id: A unique identifier for the report to which the audio belongs. For every transcribe request, a report_id is expected. This is to track which recordings are part of which report.

The user_id and unit_id do not contain privacy-sensitive information; they are merely unique numbers used for tracking usage.

It's important to note that a user can record multiple audio recordings which are part of the same report_id by stopping and starting the recording again. Therefore, for every report, a unique report_id is expected. Implementing this logic to create a unique report_id per report and sending this report_id for every recording to the API is necessary.

Models and Languages

We offer several Dutch models that are trained specifically for different healthcare domains. When creating a customer, you need to provide a model that will be used for transcribing by default. It is possible to override this default model when sending the transcribe request. If you want to update the default model of a customer, you can do so using the PUT and PATCH customer endpoints.

Usage

The usage endpoint enables you to retrieve usage statistics of reports for all your customers. In order to use this endpoint, you need to authenticate with the Management API key. By default, the endpoint returns a paginated list of hundred reports, including recording details, for the past month across all customers of the EHR vendor. You can request up to thousand results per page, and the date range difference cannot exceed more than one month. The endpoint also allows filtering on a customer level by supplying an array of customerIds in the request body. The response includes a nextPageToken if more results are available; otherwise, this token will be null. To retrieve the next page, provide the nextPageToken as a query string parameter.

Sandbox

We provide a dedicated sandbox environment for testing purposes, which mirrors the production environment, but with slightly slower performance.

Environment	Use	URL
Sandbox	Test Attendi in a test enviroment	https://sandbox.api.attendi.nl
Production	Run Attendi in a production environment	https://api.attendi.nl