Form Filling SDK Callbacks

Quick summary

Callbacks let your app respond to events during a Form filling session, such as when the interface is ready, the clinician submits a form, or the session is canceled. Pass callbacks when you call start() to handle events for that session. If you want the same handler to run across multiple sessions, use event listeners with client.on() instead.

When processing is complete, onSubmit returns the structured form data. For production, also configure a partner webhook so your server receives the results even if the browser is closed before processing finishes.

Last updated:July 2026

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

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.

function

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

function

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

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

string

required

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

string

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

MedicalFormInstance[]

Filled forms with structured output.

MedicalFormInstance[]

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

Next steps

Refer to Basic usage example for session status UI with useFormFilling() Refer to EHR handoff example for mapping generated_values to your chart Refer to Configuration for all session options

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Form Filling SDK Callbacks

Supported Form filling SDK callbacks

SDK callbacks vs webhooks

Form filling SDK events

FormFillingResult payload shape

Next steps

​Supported Form filling SDK callbacks

​SDK callbacks vs webhooks

​Form filling SDK events

​FormFillingResult payload shape

​Next steps

Supported Form filling SDK callbacks

SDK callbacks vs webhooks

Form filling SDK events

FormFillingResult payload shape

Next steps