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

# Form Filling Webhook Payload & Response

> Reference for Form filling webhook success and failure payloads, including field definitions, error codes, and every _links key

When a Form filling session reaches a final processing outcome, Suki sends a success or failure payload to your configured callback URL.

Read the top-level `status` field to identify the payload type:

* `SUCCESS`: Suki finished processing the session. This includes sessions where processing was skipped.
* `FAILURE`: Processing failed or the session was aborted.

Each payload contains the session and encounter identifiers. A success payload also contains an `_links` object with links to retrieve the filled forms and the session status. A failure payload contains an error code and description instead.

> [!NOTE]
>
> * For details about when Suki sends these notifications and how to handle each outcome, refer to [Form filling webhook overview](https://developer.suki.ai/documentation/webhook/form-filling/overview.md).
> * For request headers, signature verification, and the response your endpoint must return, refer to [Webhook request and response](https://developer.suki.ai/documentation/webhook/payload-and-response.md).

## Success payload

Suki sends a success payload when Form filling processing finishes. This includes cases where processing was skipped.

> [!NOTE]
>
> The success payload **always uses this notification shape**.
>
> * Every `_links` key is present.
> * Only `structured_data` and `status` contain links. All other keys are empty arrays on a Form filling webhook.
> * What `structured_data` returns depends on how you ran the session: the Medical form templates you bound for the session; whether you streamed live audio, uploaded a recording (`audio_file`), or submitted a finished transcript (`transcript`); and what content was available for the session.
> * A `SUCCESS` webhook does not mean every requested form was filled. Templates Suki could not fill appear in `non_generated_values` when you read the structured data.

### Fields

**status** `string` *required*

Always `SUCCESS`.

**session\_id** `string` *required*

Identifier of the Form filling session that triggered this notification. This is the session ID returned by [Create Form filling session](https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/create.md).

**encounter\_id** `string` *required*

Identifier of the encounter associated with the Form filling session.

**sessions** `array of strings`

Identifiers of all Form filling sessions in the encounter so far, ordered from oldest to newest. This list includes the session identified by `session_id`. Ambient sessions in the same encounter are not listed.

**additional\_info** `object`

Additional context about the notification.

**properties**

**session\_type** `string`

Always `FORM_FILLING` in a Form filling success payload. Use this field to identify the product when multiple Suki products send notifications to the same callback URL.

**practice\_id** `string`

Partner-facing practice identifier. Suki includes this field only when it can resolve the practice associated with the session.

**\_links** `object`

Links to the form output and session status. Every key is present in the object. Only `structured_data` and `status` contain links. All other keys are empty arrays.

Refer to [The \_links object](#the-_links-object) for the complete list of keys and their descriptions.

### Example success payload

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "SUCCESS",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "sessions": [
    "a953839a-ddcd-407d-b9b0-3ed4b6be4be2"
  ],
  "additional_info": {
    "session_type": "FORM_FILLING",
    "practice_id": "your-practice-id"
  },
  "_links": {
    "structured_data": [
      {
        "href": "/form-filling/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/structured-data",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "status": [
      {
        "href": "/session/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/status",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "contents": [],
    "transcripts": [],
    "section_structured_data": [],
    "em_codes": [],
    "diagnoses": [],
    "orders": [],
    "encounter_content": [],
    "encounter_structured_data": [],
    "encounter_section_structured_data": [],
    "encounter_em_codes": [],
    "encounter_diagnoses": [],
    "encounter_orders": []
  }
}
```

## The \_links object

The `_links` object contains the API paths your application can call to retrieve Form filling results.

Each key contains an array of link objects. Every link object has the same four fields:

| Field | Description |
| :- | :- |
| `href` | Resource path. Refer to [Build the full URL](https://developer.suki.ai/documentation/webhook/form-filling/retrieve-results.md#build-the-full-url) for how to construct the complete request URL. |
| `method` | HTTP method for the request. Always `GET`. |
| `name` | Form filling session ID associated with the resource. Use this field to identify the link for a specific session. |
| `type` | Response media type. Always `application/json`. |

Form filling creates results for each session, not for the encounter as a whole, so there are no encounter-level links.

The two keys that contain links each hold **one link for every Form filling session** in `sessions`, in the same order:

| Key | `href` pattern | Description |
| :- | :- | :- |
| `structured_data` | `/form-filling/session/{session_id}/structured-data` | Filled medical form instances, plus the templates Suki could not fill. |
| `status` | `/session/{session_id}/status` | Current processing status of the session. |

All other keys are empty arrays on a Form filling webhook.

> [!TIP]
>
> Make your webhook parser ignore unrecognized keys in `_links`. This allows your integration to handle new link types added in future releases without breaking the webhook handler.

## Failure payload

Suki sends a failure payload when Form filling processing fails or when a session is aborted.

Unlike the success payload, the failure payload does not contain `sessions`, `_links`, or `additional_info`. Instead, it includes an error code and a description of the error.

### Fields

**status** `string` *required*

Always `FAILURE`.

**session\_id** `string` *required*

Identifier of the Form filling session that failed or was aborted.

**encounter\_id** `string` *required*

Identifier of the encounter associated with the session.

**error\_code** `string` *required*

Machine-readable code that identifies the reported error. Refer to [Error codes](#error-codes).

**error\_detail** `string` *required*

Human-readable description of the error. This field can contain an empty string when Suki has no additional details.

### Example failure payload

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "FAILURE",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "encounter_id": "4d753ce1-bbff-43e1-950a-82dea2d86873",
  "error_code": "ERROR_CODE_UNSPECIFIED",
  "error_detail": "Error during form generation"
}
```

> [!WARNING]
>
> A failure payload does not contain `additional_info`, so it does not identify the product through `session_type`.
>
> If multiple Suki products send notifications to the same callback URL, match `session_id` against the Form filling session IDs your application saved when it created the sessions.

### Error codes

The `error_code` field identifies the type of error reported in the failure notification.

| `error_code` | Description |
| :- | :- |
| `ERROR_CODE_UNSPECIFIED` | Processing failed or the session was aborted. Check `error_detail` for the reported reason. |
| `ERROR_CODE_NOTIFICATION_GENERATION_FAILURE` | Suki could not prepare the webhook body for the session. In this case, `error_detail` is `Error Preparing Webhook Notification`. Call [Get Form filling session status](https://developer.suki.ai/form-filling-api-reference/form-filling-sessions/status.md) to determine the actual session outcome. |

Use `error_code` to identify and handle error conditions in your application. Log `error_detail` to help with troubleshooting or to provide context when notifying your team or clinician.

> [!TIP]
>
> `error_detail` helps you understand what went wrong in logs or when you notify your team or clinician, but Suki can revise that wording at any time. If your handler needs to choose a path, such as retry versus alert, match on `error_code` instead of comparing the detail string.

## Next steps

 **[Retrieve Form filling results](https://developer.suki.ai/documentation/webhook/form-filling/retrieve-results.md)** - Read filled forms and session status.

 **[Form filling webhook overview](https://developer.suki.ai/documentation/webhook/form-filling/overview.md)** - When Suki sends Form filling webhooks and how to handle each outcome.

 **[Webhook event catalog](https://developer.suki.ai/documentation/webhook/event-catalog.md)** - Payload references for other Suki products.

 **[Form filling asynchronous notifications](https://developer.suki.ai/form-filling-api-reference/asynchronous/webhook.md)** - OpenAPI specification and sample handlers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.