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

> Step-by-step guide to authenticate, create a session, stream audio over WebSocket, end the session, and retrieve structured form output or use webhooks

This guide walks you through the steps to use the Form Filling APIs to authenticate, create a session, provide context, stream audio through the shared Partner WebSocket (GET /ws/stream), end the session, and retrieve structured form output.

The WebSocket endpoint and message format are the same as Ambient audio streaming. Use the Form filling session ID when establishing the WebSocket connection.

**What you will do**

1. **Authenticate** to get an `sdp_suki_token` (and **register** the user if needed).
2. **Create** a Form filling session and optionally **seed context** for template metadata.
3. **Stream audio** over **`/ws/stream`** using your **Form filling** **`ambient_session_id`**, then **end** the session when the visit is done (details in the note after Step 3).
4. **Retrieve** structured form output by polling **status** and **structured-data**, or rely on a **webhook** when processing finishes.

<Tip>
  **Using an AI coding tool?**

  Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, `llms.txt`, and `skill.md`), refer to [AI-optimized documentation](/documentation/ai-optimized-documentation).

  <Prompt description="Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the [MCP server](/documentation/mcp) for documentation search." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs.

    npx skills add [https://developer.suki.ai](https://developer.suki.ai)

    Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp).
  </Prompt>
</Tip>

## Access and credentials

You need partner credentials to use the Suki Form Filling API.

Contact our [Partnership team](https://www.suki.ai/suki-partners/) to get your credentials. They will guide you through the [Onboarding process](/documentation/partner-onboarding) and provide what you need to get started.

### Prerequisites

To use the Suki Form Filling APIs, you must have the following:

* An OAuth-compliant authentication system
* JWT tokens with consistent user identifiers
* A publicly accessible <Tooltip tip="JSON Web Key Set. A set of keys containing the public keys used to verify any JWT issued by the authorization server." cta="View in Glossary" href="/Glossary/j">JWKS</Tooltip> endpoint (or Okta authorization server) for token validation

Refer to the [Partner onboarding](/documentation/partner-onboarding) and [Partner authentication](/documentation/partner-authentication) guides for more details.

### Environments to use for development and testing

This guide uses **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`** for API and WebSocket examples (staging).

<Callout icon="code" color="#FFC107" iconType="regular">
  **Important**:

  * The production environment is **`https://sdp.suki.ai`** and **`wss://sdp.suki.ai`**.
  * The staging environment is **`https://sdp.suki-stage.com`** and **`wss://sdp.suki-stage.com`**.
  * Your partnership team will confirm which environment, base URL, and credentials apply for your integration.
</Callout>

## Step 1: Authenticate and get token

To begin, you must authenticate to get your access token. Send a **POST** request to the [/api/v1/auth/login](/api-reference/authentication/login) endpoint with the following parameters in the request body:

1. **partner\_id**: Your unique <Tooltip tip="A unique identifier assigned by Suki during onboarding that links an application to its configuration in the Suki Developer Platform." cta="View in Glossary" href="/Glossary/p">Partner ID</Tooltip>, which we provide to you securely offline.
2. **partner\_token**: The user's OAuth 2.0 ID token (<Tooltip tip="A secure, digitally signed JWT issued by a partner's identity provider after user authentication, passed to Suki SDK for user verification." cta="View in Glossary" href="/Glossary/p">Partner Token</Tooltip>) from your identity provider.
3. **provider\_id** (Optional): Unique identifier for the <Tooltip tip="A healthcare professional within an organization who uses Suki's services to document patient care." cta="View in Glossary" href="/Glossary/p">provider</Tooltip>. Required for Bearer type partners only.

Suki verifies the `partner_token` using your publicly exposed **JWKS endpoint** (or your Okta authorization server URL if you use Okta). On a successful request, the API returns a <Tooltip tip="The access token returned by Suki's authentication API, used to authorize subsequent API requests to the Suki platform." cta="View in Glossary" href="/Glossary/s">Suki Token</Tooltip> (`suki_token`) that you must include as the `sdp_suki_token` header for all subsequent API calls.

<Note>
  **Handling an unregistered user**:

  * If the user is not yet registered in our system, the `/login` request will fail.
  * In this case, you must first call the [/api/v1/auth/register](/api-reference/authentication/register) endpoint to create the user, then call `/login` again.
  * You only need to call the register endpoint once for each new user.
  * Refer to the [Register API reference](/api-reference/authentication/register) for the full specification.
</Note>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "partner_id": "your-partner-id",
      "partner_token": "your-jwt-token",
      "provider_id": "provider-123"
    }'
  ```
</CodeGroup>

<Tip>
  Save the `suki_token` from the response. This token is valid for **1 hour**. When it is about to expire, you can get a new one by making the same **POST** request to `/login` with a valid `partner_token`.
</Tip>

## Step 2: Create Form filling session

To start a Form filling session, send a **POST** request to the [/api/v1/form-filling/session/create](/form-filling-api-reference/form-filling-sessions/create) endpoint with the following parameters in the request body:

<Note>
  In the API reference, both the Form filling session ID and the [Suki Ambient API session ID](/api-reference/ambient-sessions/create) are named **`ambient_session_id`**. Those identifiers refer to **different** sessions. Use only the **`ambient_session_id`** returned from **Form filling** `/session/create` for Form filling REST calls and for **`/ws/stream`**.
</Note>

1. **ambient\_session\_id** (Optional): Associate this Form filling session with an existing [Ambient API session](/api-reference/ambient-sessions/create) when applicable.
2. **correlation\_id** (Optional): Client-supplied identifier for tracing or correlating requests.

The request body itself is optional (you can send an empty JSON object). The response always includes the **`ambient_session_id`** for this Form filling session. Use that value for context, streaming, **end**, **status**, and **structured-data** calls.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  curl -X POST https://sdp.suki-stage.com/api/v1/form-filling/session/create \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

<Tip>
  Save the **`ambient_session_id`** from the response. You need it for context, **`/ws/stream`**, **end**, **status**, and **structured-data** calls.
</Tip>

## Step 3: Seed context

After creating the session, you can send a **POST** request to the [/api/v1/form-filling/session/{ambient_session_id}/context](/form-filling-api-reference/form-filling-sessions/context) endpoint to provide form template metadata.

<Note>
  The request body is **optional**. If you omit it, skip this step and continue to audio capture (see the note after this step). If you include **`form_filling`**, you must send valid **`values`**: an array of objects, each with a required **`form_template_id`** (UUID for the template). Providing **context** improves the quality of structured form output for the templates you select.
</Note>

Include the following in the request body when you supply context:

* **form\_filling** (Optional): An object with **`values`**, an array of **`form_template_id`** entries that identify which medical form templates apply to this session.

Refer to the [Context API reference](/form-filling-api-reference/form-filling-sessions/context) for the full request structure. To list templates your integration can offer, use [Suki medical form templates](/form-filling-api-reference/info/suki-medical-form-templates).

<Note>
  **Audio capture:** Stream visit audio on the Partner WebSocket **`GET /ws/stream`** on the same host as REST (for example **`wss://sdp.suki-stage.com/ws/stream`** in staging). Authenticate with your Form filling **`ambient_session_id`** and **`sdp_suki_token`**. See [Form Filling audio streaming](/form-filling-api-reference/form-filling-sessions/audio-stream) and [Ambient audio streaming](/documentation/ambient-audio-streaming) for connection and message details. When capture finishes, close the WebSocket, call **end session**, then poll **status** and **structured-data**.
</Note>

## Step 4: End session

To complete the session and begin processing, send a **POST** request to the [/api/v1/form-filling/session/{ambient_session_id}/end](/form-filling-api-reference/form-filling-sessions/end) endpoint. This signals that you will not send more audio for this session.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  curl -X POST "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/end" \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>"
  ```
</CodeGroup>

## Step 5: Poll status and retrieve structured data

When structured output is ready, Suki can notify your application. The recommended way to know when processing has finished is to use a **webhook** on the partner callback configured during onboarding. Payloads include **`_links`** you can follow to retrieve results. For verification, payload shapes, and examples, see [Form Filling asynchronous notifications (webhook)](/form-filling-api-reference/asynchronous/webhook) and [Notification webhook for partners](/documentation/webhook/overview).

**Retrieving structured output manually**: Alternatively, poll the Form filling REST endpoints:

1. [GET /api/v1/form-filling/session/{ambient_session_id}/status](/form-filling-api-reference/form-filling-sessions/status): Check the processing status of a session.
2. [GET /api/v1/form-filling/session/{ambient_session_id}/structured-data](/form-filling-api-reference/form-filling-sessions/structured-data): Retrieve **generated\_values** and **non\_generated\_values** for the session.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # Check status
  curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/status" \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>"
  # Get structured data
  curl -X GET "https://sdp.suki-stage.com/api/v1/form-filling/session/YOUR_SESSION_ID/structured-data" \
    -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
    -H "sdp_provider_id: <sdp_provider_id>"
  ```
</CodeGroup>

<Note>
  For complete technical specifications, refer to the relevant API Reference pages.
</Note>

## Next steps

After completing your first session, explore these resources to deepen your integration:

<Icon icon="file-lines" iconType="solid" /> [Form Filling API overview](/form-filling-api-reference/overview) - Overview of the Form Filling APIs.

<Icon icon="file-lines" iconType="solid" /> [Form Filling API reference](/form-filling-api-reference/authentication/register) - Reference documentation for the Form Filling APIs.

<Icon icon="file-lines" iconType="solid" /> [Form Filling audio streaming](/form-filling-api-reference/form-filling-sessions/audio-stream) - WebSocket connection details and message formats for streaming audio for Form filling sessions.

<Icon icon="file-lines" iconType="solid" /> [Form Filling asynchronous notifications (webhook)](/form-filling-api-reference/asynchronous/webhook) - Configure webhooks to receive notifications when processing completes.