PlatformClient acts as the shared runtime object for the SDK within your app. You should create a single instance of this object and reuse it throughout your application to ensure consistency.
PlatformClientProvider
The PlatformClientProvider is a React wrapper that makes your PlatformClient instance available to all child components.
This allows you to use Suki hooks, such as useAuth, useAmbient, and useAmbientSession, to build your integration quickly.
PlatformClient
Import
Before you can use thePlatformClient, you need to import it into your application.
React
Creating an instance
Create the client once for your app (for example at module scope or outside your root component) so it is not recreated on every render.React
The object you pass to
new PlatformClient({ ... }) sets how that client behaves for your app.Configuration
These are the settings you pass when you callnew PlatformClient({ ... }) in your application.
string
The Suki environment the client targets. Examples in this documentation use
"staging".boolean
When
true, the client runs in a debug-oriented mode so you can troubleshoot during development. Use false when you do not want that behavior in production.string
The logging level for the client. Examples in this documentation use
"error".PlatformClientProvider
Before you can use thePlatformClientProvider, you need to import it into your application.
Wrap your app
Create a singlePlatformClient instance and wrap your application with PlatformClientProvider. Hooks such as useAuth, useAmbient, and useAmbientSession must run under this provider.
To use Headless Web SDK, you must wrap your app with
PlatformClientProvider above any component that calls Headless Web SDK hooks. Those hooks read the shared PlatformClient from React context that the provider supplies.Refer to the Quickstart for a full component tree and useAuth example.Ambient session methods on PlatformClient
The React hooks wrap thesePlatformClient methods. Use the hooks in most React apps. Call the client directly when you are not using React, or when you want to see the underlying API the hooks delegate to.
createNewAmbientSession
Creates an ambient session on Suki’s servers and returns the ids you need for recording and note retrieval. Every create call requiresencounterId. That value groups re-ambient sessions on the same clinical note. Reuse the same encounterId whenever you start a new ambient session for that note.
Pass emrEncounterId when the note must be shared across Suki products (Web SDK, Mobile SDK, Headless Web SDK, Ambient API). Without it, the session works in your app only and is not interoperable.
string
required
Your encounter identifier for this note. Maps to Ambient API
encounter_id. Reuse the same value for every re-ambient session on that note.string
Optional: EMR or EHR encounter identifier. Maps to Ambient API
emr_encounter_id. Accepts a UUID or non-UUID value, at most 36 characters. Required for interoperability across Suki products.boolean
Optional: Enables multilingual ambient capture when your partner configuration supports it.
{ ambientSessionId, noteId }. Use ambientSessionId with startAmbientSession or useAmbientSession. Store noteId when you call Ambient API note endpoints.
If another Suki product already holds the active session for the same EMR encounter, create throws PlatformError with reason: "sessionAlreadyExists". Read blockingSessionId from error.additionalProperties, then call cancelRemoteAmbientSession or endRemoteAmbientSession before you retry create. Refer to Handle ambient session conflicts.
getEncounterInfo
Looks up shared notes and ambient session identifiers for one EMR encounter. Use this when you neednoteId and session ids before you call Ambient API note-level endpoints. The method does not return note content, transcripts, or recordings.
string
required
Partner EMR or application encounter identifier. Must be non-empty. This is the method’s only argument.
{ notes }. notes is always an array, including when no notes exist. Each note includes note_id, status, timestamps, and a sessions array with optional artifact names (for example "content", "transcript", "recording").
On failure, throws PlatformError with reason: "getEncounterInfoFailed".
In React, prefer useGetEncounterInfo({ emrEncounterId }).
endRemoteAmbientSession
Ends an ambient session that is running in another Suki product and blocking create in your app. Use this aftersessionAlreadyExists when you want the remote session to finish and process any audio already captured.
Pass the blocking session id from the conflict error, not your local session id unless they are the same.
Promise<void>. Retry createNewAmbientSession with the same encounterId and emrEncounterId.
On failure, throws PlatformError with reason: "endRemoteSessionFailed".
cancelRemoteAmbientSession
Discards an ambient session that is running in another Suki product and blocking create in your app. Use this aftersessionAlreadyExists when you want to drop the remote session without generating a note from its audio.
Pass the blocking session id from the conflict error, not your local session id unless they are the same.
Promise<void>. Retry createNewAmbientSession with the same encounterId and emrEncounterId.
On failure, throws PlatformError with reason: "cancelRemoteSessionFailed".
For end-to-end interoperability workflows, refer to Ambient interoperability, Handle ambient session conflicts, and Read shared ambient notes.
Next steps
Quickstart - Install, provider,useAuth, and ambient flow.
Ambient interoperability - Share one clinical note across Ambient products.
Handle ambient session conflicts - Clear a blocking remote session, then retry create.
Read shared ambient notes - List notes and seed patient context for Web SDK handoff.
Types overview - Index of all Headless Web SDK type reference pages.
Authentication hook - useAuth configuration and behavior.
UseAuth parameters - TypeScript shape for useAuth options.