Events

Use client.on(event, handler) to listen for Form filling SDK events, such as when a session starts, becomes ready, submits results, or reports an error. Each call returns an unsubscribe function that removes the event listener. Register these listeners once when you create FormFillingClient. They remain active across all Form filling sessions created by that client. If you only need to handle events for a single session, use callbacks such as onReady, onSubmit, or onError when calling start() instead.

JavaScript

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

// Later: offSubmitted();

Refer to Callbacks for session callbacks and result payloads. Refer to Error handling for form-filling:error codes.

Event lifecycle

In a normal session, events fire in this order:

form-filling:ready

The hosted app mounted. Same moment as onReady.

form-filling:session-started

Suki created a session and assigned ambient_session_id.

form-filling:submitted

Structured data is ready. Same moment as onSubmit. The iframe is removed.

For multi-form sessions, session-started fires after the clinician taps Start on the selection screen, not when the iframe first opens.

Events types in the Form filling SDK

The Form filling SDK has the following event types:

event

Fires when the hosted Form filling UI has mounted in the iframe and is ready for the clinician. This is the same moment as the onReady callback.After this event, the selection screen (multi-form) or recording screen (single-form) appears once your form_template_ids are applied in the iframe.Payload: None

event

Fires when Suki creates the Form filling session on the server and assigns ambient_session_id.Timing:

Single-form session: fires after form-filling:ready.
Multi-form session: fires after the clinician taps Start on the selection screen, not when the iframe first opens.

Payload: SessionStartedPayload with ambient_session_id, form_template_ids, correlation_id, and timestamp.There is no matching start() or <FormFilling> callback. Listen with client.on() when you need the session ID before structured results arrive.

event

Fires when structured form data is ready for the active session in the iframe after processing completes. This is the same moment as the onSubmit callback.This event does not fire when the clinician taps submit in the UI. Processing finishes first, then the SDK delivers results.Payload: FormFillingResultFor an active session, the SDK removes the iframe after this event.If results arrive late for the same still-open session, they still use this event and onSubmit, not form-filling:background-submitted.

event

Fires when structured form data arrives for a session that is no longer the active session in the iframe. This happens when the result’s ambient_session_id does not match the session currently open in the iframe.Common scenarios include:

The clinician closes the processing or timeout screen and starts a new session before the previous session finishes.
A previous or offline session finishes processing while a newer session is already open.

Payload: FormFillingResultReact: Handle this event with onBackgroundSubmit.JavaScript: Listen for this event with client.on(). This event is not available as a start() callback.The iframe remains open when this event is fired.This event is not an indication that the currently open session is processing slowly.

event

Fires when the clinician leaves Form filling before submit, with no structured results. This is the same moment as the onCancel callback.Common scenarios include:

The clinician closes the selection screen.
The clinician confirms Cancel Session during recording.

Payload: NoneClosing the processing screen is a different event: form-filling:closed

event

Fires when the clinician taps Close on the processing screen before structured results reach the SDK.Payload: NoneonSubmit does not run for that close action. The SDK removes the iframe. Suki may keep processing on the server.For production delivery after close, use your Partner webhook.If the clinician starts a new session before those late results arrive, the SDK may deliver them as form-filling:background-submitted instead of form-filling:submitted.

event

Fires when the SDK reports a configuration or runtime error.Payload: SukiFormFillingErrorThe same error is also passed to the optional onError handler on the FormFillingClient constructor.start() does not throwRefer to Error handling for error codes.

Next steps

Refer to Callbacks for FormFillingResult and callback payloads Refer to FormFillingClient for client.on() and start() Refer to Session workflow for processing, timeout, and webhook delivery

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Event lifecycle

Events types in the Form filling SDK

Next steps

​Event lifecycle

​Events types in the Form filling SDK

​Next steps

Event lifecycle

Events types in the Form filling SDK

Next steps