Set Context & Retrieve Results

Quick summary

After you create a Form filling session, call setFormFillingContext with Suki templates and/or partner schemas (schema as a JSON object string on iOS). Record with the same start, pause, and resume controls as Ambient. End with endFormFillingSession() or end(), then call getFormFillingStructuredData(for: recordingId). Optionally submit submitFormFillingFeedback with generatedValues[].id.

Last updated:September 2026

This guide covers what you do after create: set which forms to fill, record the visit, end the session, retrieve structured form data for your review UI, and submit optional feedback.

You need an active Form filling session and a stored recordingId from create. Refer to Create Form filling session first.

What will you learn? In this guide, you will learn how to:

Set form context with setFormFillingContext using Suki templates, partner schemas, or both.
Record with start, pause, and resume, then end with endFormFillingSession() or end().
Retrieve filled and unfilled forms with getFormFillingStructuredData(for:).
Submit optional Form filling feedback with submitFormFillingFeedback.
Handle Form filling events, offline behavior, and context or retrieve errors.

Set Form filling context

After you create a Form filling session, call setFormFillingContext(with:onCompletion:) to tell Suki which forms to fill. You can call it anytime after create and before end, including after start. You can call it again to update the forms.

Calling it on an Ambient session returns noSessionExist.
Calling setSessionContext on a Form filling session returns noSessionExist.
values must be non-empty. An invalid shape returns invalidContext.

let context: [String: AnyHashable] = [
    SukiAmbientConstant.kFormFilling: [  // "form_filling"
        SukiAmbientConstant.kFormFillingValues: [  // "values"
            [
                SukiAmbientConstant.kFormTemplateId: "<template-uuid-from-Suki-catalogue>"
            ]
        ]
    ]
]

SukiAmbientCoreManager.shared.setFormFillingContext(with: context) { result in
    // success or invalidContext / noSessionExist
}

Context parameters

dictionary

required

Top-level Form filling context object. String key: "form_filling".

Hide properties

array of dictionaries

required

One or more form entries to fill in this session. String key: "values". Must be non-empty.Each entry must use exactly one mode: static template or dynamic schema. One call may mix both entry types.

Hide static template entry

string

required

Suki Medical form template UUID from the catalogue. String key: "form_template_id".Do not include schema, type, name, or id on a static entry.

Hide dynamic schema entry

string

required

Partner form schema as a JSON object string, not a nested Swift dictionary. String key: "schema".Serialize your schema object to a string before you put it in context.

string

Optional form type. String key: "type".

string

Optional display name. String key: "name".

string

Optional partner form id. String key: "id".If you omit it, the SDK generates a UUID. Structured data echoes it as partnerFormId.

Static and dynamic entries

Each item in values must use exactly one mode: a static Suki template or a dynamic partner schema. Never both fields on the same entry, and never neither. One call may mix static and dynamic entries in the same values array.

Mode	Required	Optional	Must not include
Static (template)	`form_template_id` (Suki catalogue UUID)	n/a	`schema`, `type`, `name`, `id`
Dynamic	`schema` as a JSON object string	`type`, `name`, `id`	`form_template_id`

On iOS, schema must be a JSON object string, not a nested Swift dictionary. Serialize your schema object to a string before you put it in context.

Example entries

Static Template
Dynamic Schema

Swift

let staticEntry: [String: AnyHashable] = [
    SukiAmbientConstant.kFormTemplateId: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
]

Swift

let schemaObject: [String: Any] = [
    "title": "Wound Check",
    "type": "object",
    "properties": [
        "wound_status": ["type": "string"]
    ]
]
let schemaData = try! JSONSerialization.data(withJSONObject: schemaObject)
let schemaString = String(data: schemaData, encoding: .utf8)!

let dynamicEntry: [String: AnyHashable] = [
    SukiAmbientConstant.kFormPartnerId: "partner-wound-1",
    SukiAmbientConstant.kFormName: "Wound Check",
    SukiAmbientConstant.kFormType: "SKIN_ASSESSMENT",
    SukiAmbientConstant.kFormSchema: schemaString
]

For schema field rules and MedicalFormType names, refer to Dynamic Form filling. For Suki catalogue IDs, refer to Form filling templates.

Record and end

Form filling uses the same recording controls as Ambient. Call start, pause, and resume the same way you do for an ambient session. Refer to Recording controls for the full workflow. When the visit is done, end the Form filling session so Suki can generate the form field values.

do {
    try SukiAmbientCoreManager.shared.endFormFillingSession()
} catch {
    print(error)
}

endFormFillingSession(): Prefer this for Form filling. It checks that the active session is Form filling, then calls end(). Calling it during an Ambient session returns noSessionExist.
end(): Also ends an active Form filling session.
cancel(): Discards the audio and produces no form output.

Retrieve structured data

After you end the session, call getFormFillingStructuredData(for:) with the recordingId you stored from create. Use the result to drive your form review UI. There is no Form filling status() API. After end, poll this method or use a Partner webhook. Do not use Ambient content, transcript, getStructuredData, or listEncounterNotes for this workflow.

SukiAmbientCoreManager.shared.getFormFillingStructuredData(for: recordingId) { result in
    switch result {
    case .success(let response):
        let generated = response.structuredData.generatedValues
        let nonGenerated = response.structuredData.nonGeneratedValues
        // Show generated as filled; show nonGenerated as not filled
    case .failure(let error):
        print(error)
    }
}

Structured data response

A successful getFormFillingStructuredData(for:) call returns structuredData with two lists: forms that have filled values, and forms that do not yet.

array

Forms that have filled field values. Show these as completed in your form review UI.

array

Forms that have no filled output yet. These often include only formTemplateId. Show them as not filled.

Each instance can include:

string

Suki instance id for this form result. Use this value as formId when you submit Form filling feedback.

string

Match this to a static Suki template you sent in context.

string

Match this to the Context id you sent on a dynamic entry.

string

Form type when present.

string

Display title when present. Optional display matching.

string

Instance status when present.

dictionary

Filled field values as [String: Any].

string

Patient id when present.

string

Correlation id for the session when present.

string

Creation timestamp when present.

Map results to the forms you sent

When structured data returns, each item is one form result. Use these fields to connect that result back to the form you put in setFormFillingContext. Do not rely on array order. The list order can differ from the order you sent.

Result field	Maps to
`formTemplateId`	The Suki `form_template_id` you sent on a static entry
`partnerFormId`	The partner `id` you sent on a dynamic entry
`title`	Optional. Often echoes the dynamic Context `name` for display

Submit Form filling feedback

After a clinician reviews the filled forms, call submitFormFillingFeedback to send a rating and optional comments. Pass the Suki instance id from generatedValues[].id as formId, and use the same recordingId from create. Rating rules match Ambient QuantitativeFeedback. This call requires network. Use submitFormFillingFeedback for forms. Do not use Ambient submitFeedback.

string

required

Suki instance id from generatedValues[].id.

QuantitativeFeedback

required

Rating object with minRating, maxRating, and rating. Same rules as Ambient QuantitativeFeedback.

string

Optional free-text comments.

let submission = FormFillingFeedbackSubmission(
    formId: generatedValue.id,  // generatedValues[].id
    quantitative: QuantitativeFeedback(minRating: 1, maxRating: 5, rating: 4),
    comments: "Optional comments"
)

SukiAmbientCoreManager.shared.submitFormFillingFeedback(
    submission,
    for: recordingId
) { result in
    // Requires network
}

Session events

Use the same SukiAmbientSessionDelegate for Form filling recording events: .started, .paused, .resumed, .ended, .cancelled, and .convertedToOfflineSession. Refer to Session events and delegates.

Do not use .suggestionsGenerated or .suggestionsGenerationFailed for form-ready UI. Those are Ambient note events. Use structured data or a webhook instead.

Offline

Form filling uses the same offline path as Ambient. After a short reconnect buffer, the SDK emits .convertedToOfflineSession, keeps recording with encrypted local audio, and uploads automatically when the network returns. Refer to Offline mode for the full workflow. Encounter queueing also matches Ambient. The encounter key is the Form filling correlationId (the same key as the Ambient session group). If an unfinished offline session already exists for that key, the next create on the same key also goes offline. Uploads for that encounter run oldest first, so a queued Form filling session is sent before a later Ambient session on the same appointment.

Errors to handle

Handle these errors when you set context, end the session, or retrieve results.

Error	When
`noSessionExist`	Wrong session kind, or no session / wrong recording state
`invalidContext`	Missing `form_filling.values`, empty `values`, both modes on one entry, or invalid `schema`
`SDKNotInitilized`	Same as today

Create-time errors such as sessionInProgress and remoteSessionConflict(blockingSessionId:) are covered in Create Form filling session. For more error detail, refer to Error messages.

Complete code example

The following example shows a happy path where you create a Form filling session, set a Suki template, start recording, end the session, and retrieve structured data. Store recordingId from create so you can pass it into retrieve after the visit.

// Store recordingId from create for end, retrieve, and feedback.
var recordingId: String?

// 1) Create the Form filling session, set context, and start recording.
SukiAmbientCoreManager.shared.createSession(
    with: [SukiAmbientConstant.kCorrelationId: appointmentId],
    sessionType: .formFilling
) { result in
    guard case .success(let response) = result else { return }
    recordingId = response.recordingId

    let context: [String: AnyHashable] = [
        SukiAmbientConstant.kFormFilling: [  // "form_filling"
            SukiAmbientConstant.kFormFillingValues: [  // "values"
                [
                    SukiAmbientConstant.kFormTemplateId: "<template-uuid-from-Suki-catalogue>"
                ]
            ]
        ]
    ]

    SukiAmbientCoreManager.shared.setFormFillingContext(with: context) { _ in
        try? SukiAmbientCoreManager.shared.start()
    }
}

// 2) After the visit: end the session, then retrieve with the stored recordingId.
func endAndRetrieveFormFillingResults(recordingId: String) {
    do {
        try SukiAmbientCoreManager.shared.endFormFillingSession()
    } catch {
        print(error)
        return
    }

    SukiAmbientCoreManager.shared.getFormFillingStructuredData(for: recordingId) { result in
        switch result {
        case .success(let response):
            let generated = response.structuredData.generatedValues
            let nonGenerated = response.structuredData.nonGeneratedValues
            // Map into your form review UI
        case .failure(let error):
            print(error)
        }
    }
}

// Call when the visit is done, using the recordingId from create:
// if let recordingId { endAndRetrieveFormFillingResults(recordingId: recordingId) }

You can also call setFormFillingContext after start(), any time before end.

Next steps

Refer to Form filling templates for Suki catalogue form_template_id values. Refer to Dynamic Form filling for XOR rules and partner schemas. Refer to Create Form filling session if you still need create and recordingId. Refer to Recording controls for start, pause, and resume. Refer to Error messages for SukiAmbientCoreError cases.

Get Started

Concepts & Feature Guides

Resources

Set Context & Retrieve Results

Set Form filling context

Context parameters

Static and dynamic entries

Example entries

Record and end

Retrieve structured data

Structured data response

Map results to the forms you sent

Submit Form filling feedback

Session events

Offline

Errors to handle

Complete code example

Next steps

​Set Form filling context

​Context parameters

​Static and dynamic entries

​Example entries

​Record and end

​Retrieve structured data

​Structured data response

​Map results to the forms you sent

​Submit Form filling feedback

​Session events

​Offline

​Errors to handle

​Complete code example

​Next steps

Set Form filling context

Context parameters

Static and dynamic entries

Example entries

Record and end

Retrieve structured data

Structured data response

Map results to the forms you sent

Submit Form filling feedback

Session events

Offline

Errors to handle

Complete code example

Next steps