Form Filling SDK Callbacks

Register onSubmit, onCancel, and event handlers for Form filling SDK sessions

Callbacks let your app run your own code when Form filling reaches key moments in a session. You pass functions to the SDK; the SDK calls them when those moments happen. You do not poll for structured data.

Registering callbacks

In JavaScript, pass callbacks on the object you give to client.start(). In React, pass the same fields as props on FormFilling.

Callback	When it runs	Required
onSubmit	Structured JSON is ready after processing, not when the clinician taps submit	Yes
onReady	The hosted UI loaded and is ready for the clinician	No
onCancel	The clinician left without submitting	No
onBackgroundSubmit	Results for a superseded session while the iframe is still open (React only): result ambient_session_id no longer matches the foreground session	No

For every session field, refer to Configuration. For required vs optional setup, refer to the JavaScript or React integration guide.

Supported Form filling SDK callbacks

Pass these callbacks on client.start() in JavaScript, or as props on FormFilling in React.

Hide Supported callbacks

onSubmit · function · required

Runs when structured results are ready after processing completes. Receives a FormFillingResult with structured_data.generated_values and non_generated_values. Map generated_values to your EHR or show results in your app.

onReady · function

Optional. Runs when the hosted UI is loaded and ready. In JavaScript, runs after start() resolves the iframe handshake.

onCancel · function

Optional. Runs when the clinician cancels during form selection or recording without submitting. No structured data is returned.

onBackgroundSubmit · function

React only. Runs for form-filling:background-submitted: results whose ambient_session_id no longer matches the foreground session (replaced or reopened session), not merely because processing took longer than 60 seconds. Use the same handler shape as onSubmit.

SDK callbacks vs webhooks

After the clinician submits, Suki processes the session before structured JSON is ready. Your app can receive those results in two places:

Where	What receives results	Best for
Browser	onSubmit callback	Showing filled forms or confirming success while the clinician is still in your app
Server	Partner webhook	Saving structured data to your EHR or backend

onSubmit and your webhook receive the same structured payload. The callback runs in the browser when processing completes. The webhook runs on your server.

Do not rely on onSubmit alone to save results. The clinician may close the tab before processing finishes and before your app persists the data.

Refer to Session workflow and the Webhook handler example.

Form filling SDK events

Session callbacks run for one start() call or one FormFilling mount. client.on() stays wired across many sessions, which is useful for logging, analytics, or a shared error handler.

Subscribe once when you create the client:

JavaScript

const offSubmitted = client.on("form-filling:submitted", (result) => {
  console.log(result.ambient_session_id);
});

// Later, on app teardown:
// offSubmitted();

Event	When
form-filling:ready	Hosted UI loaded and ready
form-filling:session-started	Session created after form selection (or immediately for single-form)
form-filling:submitted	Structured data ready for the active session
form-filling:background-submitted	Results for a superseded session (result ambient_session_id ≠ foreground session)
form-filling:cancelled	Clinician cancelled during selection or recording
form-filling:closed	Clinician closed the processing screen before results reached the SDK
form-filling:error	Configuration or runtime error

Refer to Events for payload fields and Event handling example for a full listener setup.

FormFillingResult payload shape

FormFillingResult is the JSON object the SDK sends when a session finishes processing and structured form data is ready. It is not sent when the clinician taps submit; the SDK still processes the recording first.

Your handler receives a FormFillingResult from onSubmit, onBackgroundSubmit, form-filling:submitted, or form-filling:background-submitted. Use it to match the session to your patient record and map filled forms into your EHR.

Field	What to use it for
ambient_session_id	Suki session UUID. Use it to deduplicate saves. This is the Form filling session ID, not an ambient clinical note session ID.
correlation_id	Your encounter UUID, if you passed correlation_id at session start. Match it to the patient record in your app.
structured_data.generated_values	Forms with filled values. Map each data object to your EHR using form_template_id and type.
structured_data.non_generated_values	Templates with no output in this session. Entries are often sparse: only form_template_id may be set. Skip them or show an empty state.

JSON

{
  "ambient_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "structured_data": {
    "generated_values": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "form_template_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "title": "Skin Assessment",
        "status": "MEDICAL_FORM_STATUS_COMPLETED",
        "type": "SKIN_ASSESSMENT",
        "correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "data": {
          "location": "left forearm",
          "size_cm": 2.5
        }
      }
    ],
    "non_generated_values": [
      {
        "form_template_id": "8b3e2a1f-4c5d-6e7f-8901-234567890abc"
      }
    ]
  }
}

Each item in generated_values is a MedicalFormInstance: id, form_template_id, title, status, type, data, and optional correlation_id. Refer to FormFillingResult above for the full field list.

Show FormFillingResult fields

ambient_session_id · string · required

Suki Form filling session UUID. Use for deduplication and webhook matching.

correlation_id · string

Optional. Your encounter UUID from session start, if you passed correlation_id at start() or on FormFilling.

structured_data.generated_values · MedicalFormInstance[]

Filled forms with structured output.

structured_data.non_generated_values · MedicalFormInstance[]

Templates with no output. Often sparse: only form_template_id is present.

Next steps

Basic usage example - Session status UI with useFormFilling().

EHR handoff example - Mapping generated_values to your chart.

Configuration - All session options.