Updated:Starting with Mobile SDK
v2.7.0, you can list and read shared clinical notes across Suki products.Learn more in the Shared notes across products section.Quick summary
After an ambient session ends, use the Mobile SDK to check processing status and retrieve the generated content. Use
To access clinical notes shared across Suki products, use
status(for:) to check processing status, content(for:) to retrieve the clinical note, transcript(for:) to retrieve the transcript, and getStructuredData(for:) to retrieve structured output. These session-level APIs require a valid sessionId.To access clinical notes shared across Suki products, use
listEncounterNotes, getNoteContext(noteId:), getNoteContent(noteId:), getNoteStructuredData(noteId:), and encounterContent(encounterId:). Pass the compositionId as the noteId for note-level APIs. For encounterContent(encounterId:), pass the Session Group ID as encounterId, not the EMR encounter id. All of these APIs are asynchronous.- Check the processing status of a session using the
status(for:)method. - Retrieve generated content by calling the
content(for:)method to get clinical note suggestions. - Retrieve the full transcript of the conversation using the
transcript(for:)method. - Get structured data, such as generated diagnoses and entities, using the
getStructuredData(for:)method. - List and read shared notes across products with
listEncounterNotes(emrEncounterId:),getNoteContext(noteId:),getNoteContent(noteId:),getNoteStructuredData(noteId:), andencounterContent(encounterId:). - Submit user feedback on AI-generated content using the
submitFeedback(_:for:onCompletion:)method, including both quantitative and qualitative data. - Handle asynchronous results using a completion handler for all retrieval methods.
- Understand and adhere to constraints for submitting feedback, including providing feedback only once per entity type per session.
Before calling session-scoped methods, ensure the Mobile SDK is initialized and that you use a valid
sessionId from an active or completed session. Note-level methods use the same token provider and take an EMR encounter id or composition id instead.Check status and retrieve content
After you end a session, asynchronously check its processing status and retrieve the generated content. You must provide a validsessionId for the session you want to query.
The diagram below illustrates the process of retrieving the generated content of a session.
All retrieval methods are asynchronous. The result is returned in a , which provides either the requested content or an error.
Check the processing status
Callstatus(for:) after a session ends to check whether Suki has finished processing the audio. The clinical note, transcript, and structured data are only available once processing is complete, so use this method to decide when to call the retrieval methods and to drive a “processing” or “note ready” state in your UI.
Suki needs at least one minute of audio to generate content. If a session was too short or is not yet complete, the status reflects that, and the retrieval methods return no content.
Get generated suggestions
Callcontent(for:) to retrieve the AI-generated clinical note: the suggestions your provider reviews, edits, and signs before handoff to the EHR. This is the primary output most integrations display after a visit.
Call it only after status(for:) reports that processing is complete. Calling it earlier returns no content.
Get the audio transcript
Calltranscript(for:) to retrieve the word-for-word text of the conversation, which is separate from the generated clinical note. Use it when you need exactly what was said rather than the summarized note, for example to let a provider verify the note against the transcript, support QA or compliance review, or display the transcript alongside the note.
The response contains transcript segments. The example below joins them into a single string.
Get structured data
CallgetStructuredData(for:) when you need discrete, machine-readable output instead of free-text notes, for example to populate diagnosis fields, drive orders, support medical coding, or feed analytics in your application. It returns diagnoses and other entities generated from the session.
Starting with Mobile SDK
v2.6.0, the response may include Medication orders when that capability is enabled for your integration. Medication orders are optional, so check for them before you use them, as shown below.Shared notes across products
status(for:), content(for:), transcript(for:), and getStructuredData(for:) retrieve the processing status or generated content for a single ambient recording session. Each method requires a sessionId.
To list or retrieve clinical notes shared across Suki products, use the note read APIs described below. Depending on the API, pass one of the following:
- An EMR encounter id
- A
compositionIdas thenoteId - A Session Group ID as
encounterIdforencounterContent
SukiStatus. These APIs use the same token provider configured for the ambient session APIs.
For more information, see Ambient interoperability.
method
Lists compositions for an EMR encounter so you can discover shared notes across products.
method
Reads note-level context for a shared clinical note.
method
Reads note content (suggestions) for a shared clinical note.
method
Reads structured note data for a shared clinical note.
method
Reads encounter-level content for a Session Group. This is not an EMR encounter lookup.
Note read method signatures
The following are the method signatures for the note read APIs in the Mobile SDK.Swift
List encounter notes and get note content
Swift
Submit user feedback
New Submit user feedback for the AI-generated content.submitFeedback(_:for:onCompletion:) to capture how well a generated note matched the encounter, so Suki can improve future note quality. Use it after a provider reviews the content, for example behind a star rating or thumbs control with an optional comment box.
You capture both quantitative feedback (a rating) and qualitative feedback (comments) in a single submission.
Function signature
The method takes aFeedbackSubmission, the sessionId for the session you are rating, and a completion handler. On success, the handler returns a unique feedbackId; on failure, it returns an error.
Required data structures
To submit feedback, construct aFeedbackSubmission. It combines a FeedbackEntity (what the feedback is about), a QuantitativeFeedback (the rating and its scale), and an optional comments string for free-text feedback.
Implementation example
To submit feedback, you first create theFeedbackSubmission object and then pass it to the submitFeedback method along with the sessionId.
The method is asynchronous. The completion handler returns a Result containing either a success message with the unique feedbackId or an error if the submission failed.
Rating system
-
The
maxRatingmust be greater than theminRating. -
The rating must be within the inclusive range of
minRatingandmaxRating. -
The
commentsstring is optional and has a maximum length of 2000 characters.
-
Configure any integer rating scale. For example, create a 1 to 5 scale by setting
minRatingto 1 andmaxRatingto 5, or a binary scale by setting the values to 0 and 1. - Suki recommends using a scale of 1 to 5 for ratings.
FAQs
Why Is the Content Not Being Generated?
Why Is the Content Not Being Generated?
The content is not being generated because the session is not in a completed state or the session was too short. We require a minimum of 1 minute of audio to generate content. You must ensure that the session is in a completed state before retrieving the content.
Why Is the Content Not Being Retrieved?
Why Is the Content Not Being Retrieved?
The content is not being retrieved because the
sessionId is not valid. You must ensure that you are using a valid sessionId from an active or completed session.How Do I Know If the Content Has Been Generated?
How Do I Know If the Content Has Been Generated?
Check the status of the session to determine if the content has been generated.
How Do I Know If the Content Has Been Retrieved?
How Do I Know If the Content Has Been Retrieved?
Check the status of the session to determine if the content has been retrieved.
What Happens If the Internet Connection Is Lost?
What Happens If the Internet Connection Is Lost?
If the internet connection is lost, the content will be retrieved when the connection is restored. Please refer to the Offline mode guide for more information.
What Happens If the Session Is Not Completed?
What Happens If the Session Is Not Completed?
The content will not be retrieved if the session is not completed. You must ensure that the session is in a completed state before retrieving the content.
Verify your integration
After you complete your first ambient session, verify that you can:- Check the session status with
status(for:)and confirm processing is complete. - Retrieve the clinical note with
content(for:)and the transcript withtranscript(for:). - Access structured data, such as diagnoses and entities, with
getStructuredData(for:).