> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> 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.

```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const offSubmitted = client.on("form-filling:submitted", (result) => {
  console.log(result.ambient_session_id);
});

// Later: offSubmitted();
```

Refer to [Callbacks](/form-filling-sdk/guides/callbacks) for session callbacks and result payloads. Refer to [Error handling](/form-filling-sdk/guides/error-handling) for `form-filling:error` codes.

## Event lifecycle

In a normal session, events fire in this order:

1. `form-filling:ready` - the hosted app mounted. Same moment as `onReady`.
2. `form-filling:session-started` - Suki created a session and assigned `ambient_session_id`.
3. `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

<Expandable title="All events" defaultOpen="true">
  <ResponseField name="form-filling:ready" type="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.
  </ResponseField>

  <ResponseField name="form-filling:session-started" type="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.
  </ResponseField>

  <ResponseField name="form-filling:submitted" type="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**: `FormFillingResult`

    For 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`.
  </ResponseField>

  <ResponseField name="form-filling:background-submitted" type="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**: `FormFillingResult`

    React: 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.
  </ResponseField>

  <ResponseField name="form-filling:cancelled" type="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**: None.

    Closing the processing screen is a different event: `form-filling:closed`.
  </ResponseField>

  <ResponseField name="form-filling:closed" type="event">
    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](/documentation/webhook/overview).

    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`.
  </ResponseField>

  <ResponseField name="form-filling:error" type="event">
    Fires when the SDK reports a configuration or runtime error.

    **Payload**: `SukiFormFillingError`

    The same error is also passed to the optional `onError` handler on the `FormFillingClient` constructor.

    `start()` does not throw.

    Refer to [Error handling](/form-filling-sdk/guides/error-handling) for error codes.
  </ResponseField>
</Expandable>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Callbacks](/form-filling-sdk/guides/callbacks) for `FormFillingResult` and callback payloads

<Icon icon="file-lines" iconType="solid" /> Refer to [Formfillingclient](/form-filling-sdk/api-reference/form-filling-client) for `client.on()` and `start()`

<Icon icon="file-lines" iconType="solid" /> Refer to [Session workflow](/form-filling-sdk/guides/integration-patterns) for processing, timeout, and webhook delivery