Getting Started

Getting Started and Overview of Suki Platform APIs

Suki Ambient API

Our Ambient Clinician Note Generation is a set of APIs designed to facilitate the creation of clinician notes. These APIs allow you to send provider and encounter data, retrieve the generated clinician note, and access transcriptions. This enables seamless integration into healthcare applications, streamlining clinical documentation workflows.

How It Works: The Core Workflow

Integrating with the Suki Ambient API follows a straightforward, session-based workflow. At a high level, you will:

• Authenticate: Securely log in to receive a sdp_suki_token for accessing the system.
• Create a Session: Initiate a new session for a specific patient encounter to get an ambient_session_id.
• Stream Audio: Send a real-time audio stream of the patient-clinician conversation to our WebSocket endpoint.
• End Session: Signal that the conversation is over, which triggers the AI-powered note generation process.
• Retrieve Content: Fetch the final, structured clinical note and the full transcript once processing is complete.

Before You Begin: Access & Credentials

To ensure a guided onboarding and secure integration, access to our Ambient APIs requires specific partner credentials. Before you can make your first API call, you will need to obtain these credentials.

1. Obtain Access: If you are interested in using our Ambient APIs, please reach out to our partnership team. They will guide you through the onboarding process and necessary access.

Getting started with ambient APIs

The detailed, step-by-step guide below outlines the APIs and their flow for establishing an online ambient session that generates a clinical note from a clinician-patient conversation in a healthcare setting.

For comprehensive API specifications, please refer to the appropriate API reference page.

Client < > Suki Interaction

Authentication

Client sends a request to /login REST API with the payload containing partner_id (generated and shared securely with Client offline) and partner_token which is an OAuth 2.0 ID token for Client users.

Steps

1. Suki will verify the ID token using a publicly exposed JWKS endpoint (or an Okta authorization server URL if the identity manager is okta).

2. Suki will check if the user is registered using a unique identifier for the user. By default, “email” is checked. However, it can be configured to any unique identifier for users such as sub etc. If the user is not registered, then an error response will be sent back asking the client to register the user. The client then needs to call the /register endpoint.

3. Suki will issue a token (called, sdp_suki_token) in response to the call and this should be used for all subsequent calls.

4. When the token is about to expire, Client can request another token with the same /login call. Client manages their ID token and its lifetime while Suki just verifies it and issues Suki token that can be used to consume ambient functionality

Registration

Client makes /register call to register a user. This is a one-time call and subsequent to successful registration for a user, this call won’t be needed. To be added: Add endpoint here

Session Creation

The request parameter session_group_id will be changed to encounter_id soon. This document uses encounter_id to state the purpose of the parameter clearly instead of session_group_id.

Client makes a call to /session/create with the payload containing encounter_id and ambient_session_id.

1. ambient_session_id is a UUID v4. If the Client does not populate ambient_session_id then Suki will create one and share in response.
2. encounter_id corresponds to a unique identifier for the encounter (also called visit) and can be any alpha-numeric string up to 255 characters in length.

Context

Client makes the call to seed additional metadata for the session. This information significantly influences the accuracy of the note generated and is thus preferred to have.

The payload for this call includes:

a. provider_specialty: Specialty of the provider such as cardiology.

b. sections: Clinical sections that are needed to be summarized such as Assessment and Plan, Chief Complaint etc. It is a list of entities with each entity containing a title and a description. If this is not provided a default set of sections will be used. Refer Appendix A for list of standard sections.

c. patient_dinfo: Patient information which includes:

i) date of birth of the patient for accurate age information. No default is used. ii) patient sex information (MALE|FEMALE|UNKNOWN|OTHER). Defaults to UNKNOWN.

Streaming

Partner will stream raw audio data to Suki using LINEAR16 (16KHz sampling rate) over the mono channel. Audio should be chunked into 100ms packets for optimal performance.

Client sets up a wss:// request with suki endpoint /stream. It supports two types of messages:

1. AUDIO carrying raw audio data in supported format.
2. EVENT signifying event on the stream. Supported events are:

i. PAUSE: pause the stream

ii. RESUME: resume the stream

iii. CANCEL: user cancels the stream

iv. ABORT: stream is aborted (interruption)

v. KEEP_ALIVE: pings to sustain the stream during inactivity such as during paused state.

vi. EOF: indicates closure of stream

• KEEP_ALIVE must be sent once every five seconds or (preferably) less to sustain the stream.

• When the system is not in paused state, Suki system disconnects the stream when there has been no audio data after 25 seconds.

• When the system is in paused state and KEEP_ALIVE packets are being sent, Suki system disconnects the stream when there has been no audio data after 30 minutes. Put simply, Suki tolerates a silence of 1 hour when paused by client.

• When users CANCEL, the session won’t be considered and no summary will be generated.

• When users ABORT, the session will be considered and summary will be generated for whatever data (transcripts) are available. The session is active and retained so resuming streaming using the same ambient_session_id continues the session.

Note Generation

Client makes a call to /session/end to indicate completion of session. No more audio data will be coming in the session. This call triggers the summary generation process.

[New] Suki will send an event to Client that session summary is generated via an event webhook (TBD) registered with Client and designed by Suki.

1. Suki will use a simple authentication method for this posting of events. Either JTI + signatures or Client ID token can be used.

[Optional] Client can call /status REST API to check and obtain status of the session, if needed. Clients can call /content REST API to retrieve the payload by ambient_session_id supplied by Suki. Clients can call /transcript REST API to obtain completed transcripts for the session. The response payload includes transcription start time, end time and text of the transcript.

Assistant

Responses are generated using AI and may contain mistakes.