Skip to main content
When Suki sends a SUCCESS Ambient webhook, the payload includes links to the session status, note, transcript, structured data, and other results for that encounter.
The webhook does not contain the generated note or other result bodies. Your application must call the linked Ambient API endpoints to retrieve them.
Before you fetch anything else, call the status link for the session in the notification. Load the note with contents only when that status is completed. Pull the transcript, structured data, E/M codes, diagnoses, or Medication orders the same way when your product needs them. Each href is relative to /api/v1/ambient. Join your Ambient API base URL with that path, and authenticate the request with your Suki Token.

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 Ambient API requests with the sdp_suki_token header. Include the sdp_provider_id header when your partnership requires it. Refer to Ambient API quickstart.

Build the full URL

Each href in an Ambient webhook link is relative to the Ambient API path, /api/v1/ambient. Append /api/v1/ambient and the href to your API base URL to build the full request 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.

Available endpoints

This table maps each _links key to its Ambient API endpoint and API reference page. Every link object includes a method field. Use that method when you call the endpoint. For the links in this table, the method is always GET.
Diagnoses and Medication orders are Ambient API results. The published API reference documents them on the session and encounter structured data pages. The webhook also includes dedicated diagnoses and orders links. Call those href values when you only need that slice, or call structured_data / encounter_structured_data when you want the full structured data response documented in the API reference.

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 Ambient API calls to finish before you respond. Process the notification and retrieve results in a background job.

Select the Correct Links

  • Read _links and select the keys you need.
  • Session-level arrays contain one link for each 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.
  • Encounter-level arrays contain one link for the entire encounter.

Check the Session Status

  • Call the status link for the current session. Retrieve the note and other content only when the returned status is completed.
  • If the status is skipped, Suki did not generate a note for that session. Skip the content requests and offer the clinician a chance to record again.
  • Do not treat every non-completed status as skipped. Handle failed, aborted, and in-progress values according to the status API response. Refer to Track note generation status.

Retrieve the Required Results

  • Call contents for the selected session’s note. Use encounter_content when your application needs the combined encounter note.
  • Call the transcript, structured data, E/M codes, diagnoses, and Medication orders links only when your application needs those results.
For help choosing session-level versus encounter-level note content, refer to Get shared note content.
A link in _links does not guarantee that the response contains values. em_codes, diagnoses, and orders can return HTTP 200 with an empty values list. Refer to Retrieve E/M codes, diagnoses, and Medication orders.

Example: retrieve one session note

The following examples retrieve the note for the session that triggered the webhook. Keep this path focused on status and contents. The endpoint table above lists every other key. 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 status link for that session.
  3. Continue only when the session status is completed.
  4. Retrieve the session note through the contents link.
The examples use the production API base URL. Replace it with the staging base URL when you test against staging.

Code example

Example: retrieve other results

After status is completed, reuse the same base URL, Ambient path, headers, and helper. Change only the _links key.

Session transcript

Match name to session_id, the same way you select contents.

Code example

Encounter note content

Encounter-level arrays hold a single link. Use the first entry. Do not match on session_id.

Code example

Use the same pattern for structured_data, em_codes, diagnoses, orders, and the other encounter-level keys in the endpoint table.

Responses from linked endpoints

When you call a linked Ambient API endpoint, 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.
  • 5xx Server Error: Retry the request after a short delay.

Next steps

Ambient payload reference - Every field and link key in the webhook body. Track note generation status - Show the right state to clinicians. Get the generated note - All the ways to load notes and structured data. Webhook request and response - The 200 response, retries, and duplicate deliveries.
Last modified on November 5, 2026