Getting started

Configure your tenant and learn how to start using Attendi

Learn about setting up customers, units, and reports; the different environments Attendi offers, such as sandbox and production; and how to securely authenticate and manage API keys to access our services and various available APIs.

Attendi also offers client SDKs for web, Android, and iOS. They contain the Attendi Microphone — a customizable component simplifying the process of adding speech processing capabilities to your application, providing a smooth and intuitive user experience. See the client SDK page for more information.

Development environment: sandbox

We provide a dedicated sandbox environment for development and testing purposes. This environment mirrors the production environment but with slightly slower performance.

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

Important: All partners are required to use the sandbox environment for development and testing purposes. For demos to potential customers or for real usage, the production environment should be used.

Management and feature APIs

Attendi's APIs can be divided into two categories:

• management: Manage metadata such that usage for customers and units can be tracked and authenticated. The management endpoints are authenticated using a secret key, which we provide to you on request. For more information, see the API key management section.
• feature: Provide functionality such as transcription.

To use the feature APIs, your tenant must be set up correctly using the management APIs. This includes creating the appropriate customers and units.

Customers and units

info

The management endpoints are authenticated using a secret key of the form sk_<key>, which we provide to you on request.

A customer refers to a healthcare organization whose healthcare professionals will be using the feature APIs. A unit refers to a team within that healthcare organization.

This separation allows you and your customers to track usage of different teams, so that you are aware of varying levels of activity and adoption of Attendi's features.

Before a customer can start using the feature APIs, you first create a customer, after which you create the appropriate units for that customer.

As an example, let's assume you want to onboard a customer HappyCare with two teams: JoyfulTeam and CheerfulTeam (make sure to use the sandbox environment if creating test customers and units). You would:

1. Create the customer HappyCare.
2. Create the units JoyfulTeam and CheerfulTeam.

To create a customer, call the PUT /customers/{id} endpoint:

curl -X PUT \
  'https://api.attendi.nl/v1/customers/{id}' \
  -H 'x-API-key: <your_secret_key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "HappyCare",
  "defaultModel": "DistrictCare"
}'

where:

• id is a string uniquely identifying the customer in your system. This id will be used to manage that customer using the management APIs.
• name is the name of the customer.
• defaultModel is the default model to use for transcriptions. We have different models for different healthcare domains. The full list can be found in the PUT /v1/customers request body schema.

If the request is successful, you will receive the following response:

{
  "id": "<customerId>",
  "name": "HappyCare",
  "defaultModel": "DistrictCare",
  "apiKeys": [
    {
      "id": 0,
      "ExpiresAt": "<timestamp>",
      "key": "ck_<key>"
    }
  ]
}

where apiKeys is an array of customer keys. Each key has an expiration date and a unique key that can be used to authenticate requests to the feature APIs.

It's important to store the id and apiKeys in your system, as you will need them to manage the customer and authenticate requests to the feature APIs.

You've successfully created the customer HappyCare! Next, create the units JoyfulTeam and CheerfulTeam using the PUT /customers/{customerId}/units/{id} endpoint:

CUSTOMER_ID="<customerId>"

curl -X PUT \
  'https://api.attendi.nl/v1/customers/$CUSTOMER_ID/units/{id}' \
  -H 'x-API-key: <your_secret_key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "JoyfulTeam",
  "users": 10
}'

curl -X PUT \
  'https://api.attendi.nl/v1/customers/$CUSTOMER_ID/units/{id}' \
  -H 'x-API-key: <your_secret_key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "CheerfulTeam",
  "users": 20
}'

where:

• id is a string uniquely identifying the unit in your system. This id will be used to manage that unit using the management APIs.
• name is the name of the unit.
• users is the amount of potential users in the unit.

There are several endpoints for creating, updating and retrieving customers and units. See the Swagger documentation for a complete reference. 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.

Any customers created in the sandbox environment will not be available in the production environment, and vice versa. These environments are completely separate.

tip

Keeping the customer and unit data in sync with your internal systems is important. One convenient way to do this is checking whether the unit exists in our system before calling a feature API. If it doesn't, create the unit. This way, the whole system stays automatically up to date with any changes and new teams. For example:

CUSTOMER_ID="<customerId>"
UNIT_ID="<unitId>"

curl -X GET \
  'https://api.attendi.nl/v1/customers/$CUSTOMER_ID/units/$UNIT_ID' \
  -H 'x-API-key: <your_secret_key>'

# If response status is 404, the unit does not exist, so create it.
if [ $? -eq 404 ]; then
  curl -X PUT \
    'https://api.attendi.nl/v1/customers/$CUSTOMER_ID/units/$UNIT_ID' \
    -H 'x-API-key: <your_secret_key>' \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "JoyfulTeam",
    "users": 10
  }'
fi

Authentication

To authenticate your requests, include your API key by adding the custom x-API-key HTTP header (case insensitive).

We use two types of API keys: secret keys and customer keys. Each type has its own prefix, making them easy to distinguish. Separate keys are provided for sandbox and production environments.

• Secret keys: Used with management APIs. These keys should be treated as highly confidential and should never be shared in publicly accessible areas. Handle them 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

API key management

Use the POST /v1/api_keys/{id}/roll endpoint to revoke the customer key identified by id and create a new key. Accepts a request body parameter indicating the amount of seconds in which the key should expire. Keys that have been rolled can be deleted completely with the DELETE /v1/api_keys/{id} endpoint. For example, if we want to roll a key one minute from now:

curl -X POST \
  'https://api.attendi.nl/v1/api_keys/{id}/roll' \
  -H 'x-API-key: <your_secret_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "expiresIn": 60
  }'

which will return a new key:

{
  "id": <new_api_key_id>,
  "key": <new_api_key_value>
}

If you want to delete the key now:

curl -X DELETE \
  'https://api.attendi.nl/v1/api_keys/{id}' \
  -H 'x-API-key: <your_secret_key>'

Retrieve usage data

Use the POST /v1/usage/reports to retrieve report metadata for all your customers. This can for instance be used to build dashboarding for your customers.

curl -X POST \
  'https://api.attendi.nl/v1/usage/reports?DateFrom=2024-03-15&DateTo=2024-04-15&PageSize=100&NextPageToken=eyJDdXJzb3IiOjEzMTE5MDYsIlBhZ2' \
  -H 'x-API-key: <your_secret_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerIds": ["<customerId>"],
  }'

where:

• DateFrom: Start date for filtering. If no value is supplied, a month ago from today is used.
• DateTo: End date for filtering. If no value is supplied, the current date is used. The difference between the start and end date must be at most one month.
• PageSize is the number of results per page. Defaults to 100. The maximum is 1000.
• NextPageToken is the token to retrieve the next page of results. It's null if there are no more results.
• customerIds is an array of customer IDs to filter on. If no value is supplied, all customers are included in the report.

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.

Transcription

Use the POST /v1/speech/transcribe endpoint to transcribe an audio recording. The audio should be a base64-encoded wav file with the following specifications:

• Single (mono) channel recording
• 16 kHz sampling rate
• 16-bit signed integer PCM encoding

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

The request body should look like this:

{
  "audio": "<base64_encoded_wav_file>",
  "userId": "<userId>",
  "unitId": "<unitId>",
  "config": {
    "model": "<model>"
  },
  "metadata": {
    "reportId": "<reportId>",
    "userAgent": "<userAgent>"
  }
}

where:

• userId is 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.
• unitId is an identifier for the unit (team) the user is part of. Based on this identifier received in the request, we can link and track the usage per team. This unitId 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.
• model: The model to use for transcription. If not given, we use the default that was given when creating the customer. We have different models for different healthcare domains. The full list can be found in the POST /v1/speech/transcribe request body schema.
• reportId: A unique identifier for the report to which the audio belongs. For every transcribe request, a reportId is expected. This is to track which recordings are part of which report, as multiple recordings can be part of the same report.
• userAgent: The user agent of the client that recorded the audio.

The userId and unitId should not contain privacy-sensitive information; they are merely unique numbers to track usage.

It's important to note that a user can record multiple audio recordings which are part of the same reportId by stopping and starting the recording again. Therefore, for every report, a unique reportId is expected. Implementing this logic to create a unique reportId per report and sending this reportId 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 default model for a customer. 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.

Preconditions for a successful integration

Before a software partner can start using our solution in production and the integration is considered done, the following technical requirements must be met:

• Ensure that all teams (units) are created in our environment using the unit endpoint.
• For every request, send a unitId, userId and reportId as described above.
• If the audio is longer than 6 minutes, the remaining audio will be ignored, and the transcription will be based on the first 6 minutes. As this is not a good experience for the user, only allow a duration of up to 6 minutes in your application. While our maximum duration is 6 minutes, your maximum duration should be set a bit lower than this.

If these requirements aren't met, we can't consider the integration complete and our solution won't be ready for production use.

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.