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

> Introduction to the Suki Form Filling API: REST, shared Partner WebSocket audio, webhooks, sessions, and structured medical form output

Suki provides **REST APIs** that let you add **structured medical form workflows** to your application. The APIs give you full control over your application workflows and user experience while enabling you to capture visit conversations and generate completed forms.

The Form Filling APIs support sessions for both **in-person** and **virtual** encounters. During a session, clinicians or other staff collect patient information and receive **structured form output** based on Suki-defined templates. Most operations use <Tooltip tip="Representational State Transfer. A software architectural style used for building web services.">REST</Tooltip> endpoints and return standard [HTTP status codes](/api-reference/https-guidelines).

Visit 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`) by using your Form filling session ID. <Tooltip tip="HTTP callbacks sent to your service for asynchronous events and status updates.">Webhooks</Tooltip> notify your application when processing is complete, which removes the need for continuous polling.

## Key capabilities

The Form Filling APIs expose the capabilities below 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">
    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/partner-onboarding) documentation.
* HTTP/2.0 compliant authentication system (e.g. OAuth 2.0, JWT, etc.).
* JWT tokens with consistent user identifiers (e.g. `sub`, `email`, `userId`, etc.).
* 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 or telehealth visits etc.

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>

## Available APIs

The following groups cover authentication, session lifecycle, retrieval, feedback, and template discovery for Form filling integrations.

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

## 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 to start a new visit.
  </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 session when the visit is complete" icon="circle-xmark">
    End the session when the visit is complete.
  </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.