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.

• For details about when Suki sends these notifications and how to handle each outcome, refer to Form filling webhook overview.
• For request headers, signature verification, and the response your endpoint must return, refer to Webhook request and response.

​

Success payload

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

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.

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.

Show 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 for the complete list of keys and their descriptions.

​

Example success payload

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

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

{
  "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"
}

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

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 - Read filled forms and session status.

Form filling webhook overview - When Suki sends Form filling webhooks and how to handle each outcome.

Webhook event catalog - Payload references for other Suki products.

Form filling asynchronous notifications - OpenAPI specification and sample handlers.