Skip to main content
When Suki sends a SUCCESS Form filling webhook, the payload includes links to the filled form output and the session status.
The webhook does not contain the filled form values. Your application must call the linked Form filling API endpoints to retrieve them.
Use the structured_data link for the session in the notification to load the filled forms. Check generated_values for forms Suki filled and non_generated_values for templates that still need manual entry. Call the Form filling status endpoint when you need to confirm the session state. Each href is relative to /api/v1. Join your API base URL with that path for structured_data, and authenticate the request with your Suki Token. For status, use the Form filling status path described below instead of the raw status href.

Prerequisites

Before you retrieve results, make sure you have:
  • A webhook receiver: An endpoint that receives Suki webhooks and verifies their signatures. Refer to Webhook quickstart and Signature verification.
  • A valid Suki Token: Authenticate Form filling API requests with the sdp_suki_token header. Include the sdp_provider_id header when your partnership requires it. Refer to Form filling API quickstart.

Build the full URL

Form filling webhook links are relative to /api/v1, not /api/v1/ambient.

Structured data

Append /api/v1 and the structured_data href to your API base URL. For example, when the production base URL is https://sdp.suki.ai and the link contains:
the full request URL is:
For staging, use https://sdp.suki-stage.com as the API base URL.

Session status

The webhook status href looks like /session/{session_id}/status. That path is the shared session-status shape. For a Form filling session, call the Form filling status endpoint instead:
Do not call /api/v1/session/{session_id}/status for Form filling results.

Available endpoints

Every link object includes a method field. Use that method when you call the endpoint. For these links, the method is always GET. Session-level arrays hold one link for every Form filling session in the encounter. Match the link’s name to the webhook’s session_id when you want results for the session that triggered the notification. Form filling has no encounter-level links.
Other _links keys are present on the Form filling webhook but are empty arrays. Ignore them. Refer to Form filling webhook payload.

Retrieve results step by step

Follow this sequence after your webhook endpoint receives a SUCCESS notification:

Verify the Webhook and Return HTTP 200

Verify the webhook signature and return HTTP 200 within 30 seconds. Do not wait for Form filling API calls to finish before you respond. Process the notification and retrieve results in a background job.

Select the Structured Data Link

Read _links.structured_data and choose the link whose name matches the webhook’s session_id.

Retrieve the Filled Forms

Call the structured_data link. Read structured_data.generated_values for filled form instances and structured_data.non_generated_values for templates Suki could not fill.

Check Session Status When Needed

Call the Form filling status endpoint with the same session_id when you need to confirm the session state before you mark the visit done or surface an error.
A SUCCESS webhook means processing finished. It does not mean every requested template was filled. Always handle non_generated_values before you show forms to the clinician.

Read the filled forms

Example response

Check session status

Call Get Form filling session status when you need the current processing state.

Example: retrieve filled forms

The following examples retrieve structured data for the Form filling session that triggered the webhook. Run this code after your webhook endpoint has verified the signature and returned HTTP 200. The examples:
  1. Read session_id and _links from the webhook payload.
  2. Find the structured_data link for that session.
  3. Retrieve the filled forms and print generated and non-generated templates.
The examples use the production API base URL. Replace it with the staging base URL when you test against staging.

Code example

Example: check session status

Build the Form filling status URL from session_id. Do not append the webhook status href to /api/v1 unchanged.

Code example

Responses from linked endpoints

When you call the Form filling API endpoints, Suki returns standard HTTP status codes.
  • 400 Bad Request: Fix the URL or request parameters, then send the request again.
  • 401 Unauthorized: Log in again for a new Suki Token, then retry with the updated token.
  • 404 Not Found: Confirm the Form filling session_id and endpoint path.
  • 5xx Server Error: Retry the request after a short delay.

Next steps

Form filling payload reference - Every field and link key in the webhook body. Form filling templates - How templates map to filled forms. Form filling no results - What to check when no forms are filled. Webhook request and response - The 200 response, retries, and duplicate deliveries.
Last modified on November 5, 2026