Form filling SDK lifecycle events and when each one fires
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.
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.
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.
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.
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.
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: None.Closing the processing screen is a different event: form-filling:closed.
Fires when the clinician taps Close on the processing screen before structured results reach the SDK.Payload: None.onSubmit 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.
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 throw.Refer to Error handling for error codes.
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
