> ## 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 APIs Overview

> Use Form filling REST endpoints, shared Partner WebSocket audio, webhooks, sessions, and structured form output in your integration

<Callout icon="handshake" color="orange">
  **Are you a Suki partner?**

  To use any Suki API or SDK, you must be a Suki partner. Contact the partnership team to begin the onboarding process. They help you set up your authentication system and get started with the Suki APIs and SDKs.

  <div style={{ marginTop: '0.75rem' }}>
    <a className="doc-guide-btn partner-contact-cta" href="https://www.suki.ai/suki-partners/" target="_blank" rel="noopener noreferrer">
      Contact Partnership Team
    </a>
  </div>
</Callout>

Suki Form filling APIs let you integrate **structured medical form workflows** into your application. You can create and manage **Form filling sessions**, stream visit audio, and retrieve **structured form output** while maintaining full control over your application's workflows and user experience.

An <Tooltip tip="One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit." cta="View in Glossary" href="/Glossary/e">encounter</Tooltip> is the patient visit. A Form filling session is one capture instance for that visit. One encounter can include one or more Form filling sessions.

During a Form filling session, clinicians or other staff collect patient information for **in-person** or **virtual** encounters while Suki processes the streamed audio and populates Suki-defined form templates. Most operations use <Tooltip tip="Representational State Transfer. A software architectural style used for building web services.">REST</Tooltip> APIs and return standard [HTTP status codes](/api-reference/https-guidelines).

Audio is streamed over the shared Partner <Tooltip tip="A persistent, bi-directional connection used for real-time audio streaming and events.">WebSocket</Tooltip> (`GET /ws/stream`) using the Form filling session ID. When processing is complete, you can poll session status and retrieve structured data, or use a <Tooltip tip="HTTP callbacks sent to your service for asynchronous events and status updates.">webhook</Tooltip> so you do not need to poll continuously.

## Available APIs

The following set of APIs are available for the Form filling workflow. View each card below to learn more about the endpoints that are available and how to use them.

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/form-filling-api-reference/authentication" arrow={true}>
    Endpoints for authentication and authorization.
  </Card>

  <Card title="Session Management" icon="waveform" href="/form-filling-api-reference/form-filling-session-management" arrow={true}>
    Endpoints for creating, managing, streaming audio, and ending Form filling sessions.
  </Card>

  <Card title="Content Retrieval" icon="file-lines" href="/form-filling-api-reference/form-filling-content-retrieval" arrow={true}>
    Endpoints for polling session status, retrieving structured medical-form output, and session recordings.
  </Card>

  <Card title="Notifications" icon="bell" href="/form-filling-api-reference/form-filling-notifications" arrow={true}>
    Webhook specification for asynchronous Form filling session completion events.
  </Card>

  <Card title="Feedback" icon="comment" href="/form-filling-api-reference/form-filling-feedback" arrow={true}>
    Endpoints for submitting feedback for Form filling session entities.
  </Card>

  <Card title="Form Filling Info" icon="info" href="/form-filling-api-reference/form-filling-info" arrow={true}>
    Endpoints for listing Suki-defined Medical form templates for Form filling sessions.
  </Card>
</CardGroup>

## Authentication

For an overview of Suki's supported authentication mechanisms refer to [Authentication mechanisms](/documentation/how-to/partner-authentication). We recommend using OAuth 2.0 with JWT tokens for your authentication system.

If you know what your authentication model is, refer to the following guides to get started:

<CardGroup cols={3}>
  <Card title="Single Auth Token Authentication" icon="Key" href="/api-reference/single-auth-token-authentication" horizontal />

  <Card title="Standard Provider Authentication" icon="User" href="/api-reference/provider-authentication" horizontal />

  <Card title="Bearer Partner Authentication" icon="Shield-Halved" href="/api-reference/bearer-partner-authentication" horizontal />
</CardGroup>

All Suki API requests must include the following headers:

| Header          | Value                                | Required    |
| :-------------- | :----------------------------------- | :---------- |
| `Authorization` | `Bearer <suki_access_token>`         | Yes         |
| `partner_token` | JWT issued by your identity provider | Yes         |
| `Content-Type`  | `application/json`                   | Yes         |
| `Accept`        | `application/json`                   | Recommended |

<Note>
  If you're using a Suki SDK, the SDK manages authentication and sends the required headers automatically after authentication is configured.
</Note>

## Key capabilities

The Form filling APIs provide the following capabilities, so you can run voice-driven medical form workflows from template selection through structured output in your EHR or internal systems.

<Note>
  Suki provides templates for common medical forms. Refer to the [Form filling API templates](/form-filling-api-reference/form-filling-info) section to learn more.
</Note>

<CardGroup cols={2}>
  <Card title="Voice-Driven Form Capture" icon="microphone">
    Stream visit audio through the shared Partner WebSocket to generate structured medical forms during in-person and virtual visits.
  </Card>

  <Card title="Session Lifecycle Management" icon="waveform">
    Create and manage Form filling sessions, update session context, end visits, and monitor processing status until completion.
  </Card>

  <Card title="Medical Form Templates" icon="list" href="/documentation/concepts/form-filling/form-filling-templates" arrow={true}>
    Retrieve available Suki Medical form templates to support form selection, validation, and clinician workflows in your application.
  </Card>

  <Card title="Structured Form Output" icon="table">
    Retrieve generated medical form instances and structured outputs for EHR and downstream clinical workflows.
  </Card>

  <Card title="Encounter Context" icon="file-lines">
    Pass patient, provider, and template information as session context when creating or updating active sessions.
  </Card>

  <Card title="In-Person and Virtual Visits" icon="video">
    Use the same Form filling workflow for in-person and telehealth encounters while keeping control of the capture experience in your UI.
  </Card>

  <Card title="Webhook Notifications" icon="bell">
    Receive webhook events when form processing is complete so your backend can respond without relying only on polling.
  </Card>

  <Card title="Session Feedback" icon="comment">
    Collect clinician feedback and optional ratings for generated structured data to help measure form quality and user satisfaction.
  </Card>
</CardGroup>

## Requirements

Before you can use the Form filling APIs, you need to meet the following requirements:

* You must be a Suki partner. Learn more about how to become a Suki partner in the [Partner onboarding](/documentation/get-started/partner-onboarding) documentation.
* A standards-based authentication system (for example OAuth 2.0 or OpenID Connect with JWTs).
* JWT tokens with consistent user identifiers (for example `sub`, `email`, or `userId`).
* A publicly accessible JWKS endpoint for token verification.

## What you can build

Use the Form filling APIs to build custom workflows for voice-driven medical form capture. Control how sessions are created and ended, how context is supplied, how audio is streamed, and how structured outputs are presented or saved in your product.

You can align capture with:

* Intake and assessments.
* Nursing and clinician workflows.
* Medication reviews.
* In-person and telehealth visits.

Implement your own logic for session lifecycle, structured field review, editing before save, and downstream handoff, and connect to your EHR, telehealth stack, or internal systems using the Form filling REST APIs, the Partner WebSocket stream, and optional webhooks.

### Common use cases

<CardGroup cols={3}>
  <Card title="Capture Forms During In-Person Visits" icon="user">
    Clinicians select a form type, start recording, conduct the visit in the room, then generate a populated form for review and save to the patient record.
  </Card>

  <Card title="Fill Forms in Virtual Video Visits" icon="video">
    Clinicians join a telehealth visit, start recording, collect verbal responses, then generate a digital form for verification and submission.
  </Card>

  <Card title="Run Template-Driven Sessions" icon="list">
    Discover Suki-defined templates via the Medical form templates API, bind template choices in session context, and retrieve structured instances after processing.
  </Card>
</CardGroup>

## API versioning

All endpoints use the `/api/v1/` prefix. **v1** is the stable version. Non-breaking changes may ship without a major version jump. For policies and migration, refer to [API guidelines](/api-reference/api-guidelines#version-management).

<Note>
  These APIs may include Early Access features. If you are unsure what is enabled for your account, contact your Suki representative.
</Note>

## Suki Form filling APIs workflow

To integrate with the Form filling APIs, you follow a session-based workflow.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    Start([Start integration]) --> Auth[Authentication]
    Auth --> Check{User registered?}
    Check -->|No| Register[Register new user]
    Register --> Auth
    Check -->|Yes| Token[Get sdp_suki_token]
    Token --> Create["POST Form filling session create"]
    Create --> SessionID["Get Form filling ambient_session_id"]
    SessionID --> Context{Seed or update context?}
    Context -->|Yes| AddContext["POST or PATCH context"]
    Context -->|No| Stream
    AddContext --> Stream["GET /ws/stream WebSocket audio"]
    Stream --> EndSession["POST Form filling session end"]
    EndSession --> Notify{Webhook configured?}
    Notify -->|Yes| Hook[Receive notification]
    Notify -->|No| Poll["GET session status"]
    Hook --> Poll
    Poll --> Running{Terminal status?}
    Running -->|No| Poll
    Running -->|Yes| Structured["GET structured data"]
    Structured --> Recording{Retrieve recording?}
    Recording -->|Optional| Rec["GET session recording"]
    Recording -->|Skip| Feedback
    Rec --> Feedback{Submit feedback?}
    Feedback -->|Optional| FB["POST entity feedback"]
    Feedback -->|Skip| Complete
    FB --> Complete([Workflow complete])

    classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
    classDef registerStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000
    classDef highlightStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000

    class Auth,Create,Stream,Poll,Structured authStyle
    class Register registerStyle
    class EndSession highlightStyle
```

### Developer workflow

<Steps>
  <Step title="Authenticate with Suki" icon="key">
    Authenticate with Suki to get a **Suki Token**, returned as `suki_token`.
  </Step>

  <Step title="Create a Form Filling Session" icon="code">
    Create a Form filling session for the patient visit. One encounter can include more than one session.
  </Step>

  <Step title="Seed or Update Session Context" icon="file-lines">
    Seed or update session context.
  </Step>

  <Step title="Stream Visit Audio over WebSocket" icon="microphone">
    Stream visit audio over WebSocket to the Suki backend.
  </Step>

  <Step title="End the Form Filling Session When Recording Is Finished" icon="circle-xmark">
    End the Form filling session when that recording is finished. Ending a session is not the same as closing the encounter.
  </Step>

  <Step title="Retrieve the Structured Form Output After Processing Finishes" icon="file-lines">
    Retrieve the structured form output after processing finishes.
  </Step>
</Steps>

<Note>
  If webhooks are enabled for your partner account, your application will receive automatic completion notifications instead of relying only on polling.
</Note>

<Tip>
  **Best practices**

  * Store **partner\_id**, **partner\_token**, and issued tokens securely; rotate credentials per your security policy.
  * Send API traffic over HTTPS and validate webhook signatures when your integration receives callbacks.
  * Read HTTP status and error bodies from REST responses; handle auth expiry by refreshing **`sdp_suki_token`** as documented.
</Tip>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Form filling API quickstart](/form-filling-api-reference/quickstart) to get started.