> ## 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:

<Steps>
  <Step title="form-filling:ready">
    The hosted app mounted. Same moment as `onReady`.
  </Step>

  <Step title="form-filling:session-started">
    Suki created a session and assigned `ambient_session_id`.
  </Step>

  <Step title="form-filling:submitted">
    Structured data is ready. Same moment as `onSubmit`. The iframe is removed.
  </Step>
</Steps>

<Note>
  For multi-form sessions, `session-started` fires after the clinician taps **Start** on the selection screen, not when the iframe first opens.
</Note>

## Events types in the Form filling SDK

The Form filling SDK has the following event types:

* [`form-filling:ready`](/form-filling-sdk/api-reference/events#param-form-filling-ready).
* [`form-filling:session-started`](/form-filling-sdk/api-reference/events#param-form-filling-session-started).
* [`form-filling:submitted`](/form-filling-sdk/api-reference/events#param-form-filling-submitted).
* [`form-filling:background-submitted`](/form-filling-sdk/api-reference/events#param-form-filling-background-submitted).
* [`form-filling:cancelled`](/form-filling-sdk/api-reference/events#param-form-filling-cancelled).
* [`form-filling:closed`](/form-filling-sdk/api-reference/events#param-form-filling-closed).
* [`form-filling:error`](/form-filling-sdk/api-reference/events#param-form-filling-error).

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

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