> ## 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 > Turn visit conversation into structured form output with Suki Form filling templates: session workflow, API, Web SDK, and Form filling SDK paths, and EHR handoff
Form filling converts visit conversation into structured medical form output using Suki templates. Instead of typing values into forms during or after a visit, providers can speak naturally while Suki maps the conversation into template fields your application can review, edit, and save.
Form filling lets you convert clinical conversation into structured medical form output using Suki Medical form templates. Providers or nurses speak during the patient encounter while Suki maps what was said into form fields. Your application reviews, edits, and saves those values into your EHR or downstream workflow. * An encounter 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. Do not **reuse an Ambient clinical note session ID** for Form filling sessions. * Form filling is template-driven structured output. It is not ambient note generation. Use it for nursing workflows, intake and assessments, medication reviews, and other form-based documentation where you need field values, not a full clinical note. When you use Form filling, it helps clinicians and nurses to: * Complete structured medical forms through natural conversation during the visit. * Review generated field values while the visit context is still fresh. * Edit, validate, or manually complete fields before saving. * Approve or submit form data into the EHR or downstream workflow. **What you build for Form filling to work** * Select the [Medical form templates](/documentation/concepts/form-filling/form-filling-templates) in scope for the patient encounter. * Create a Form filling session for that encounter, then capture the patient-provider or patient-nurse conversation with Form filling APIs, Web SDK, or Form filling SDK modalities. * Receive structured form output for the selected templates. * Let the provider or nurse review, edit, and save the form data in your application. ## Choose your path to build Form filling workflows Suki provides three integration options for Form filling workflows. Pick the one that matches how much UI and session control you want Suki to own, and how much you want to own, then open the matching quickstart to get started. **If you need:** full control over session lifecycle, audio streaming, review UI, and EHR handoff. Your application owns create session, template context, WebSocket audio, status checks, structured data retrieval, and save logic.
Form Filling API Quickstart
**If you need:** Form filling inside an app that already uses `@suki-sdk/js` or `@suki-sdk/react`. From Web SDK `v3.2.0` or later, import the Form filling client and components from the Web SDK package. You do not need a standalone Form filling SDK install.
Web SDK Form Filling Overview
**If you need:** a hosted browser UI for Form filling without the rest of the Web SDK. Suki provides the Form filling experience. Your application opens the SDK, passes encounter context and templates, then handles submitted structured results in callbacks or webhooks.
Form Filling SDK Quickstart
Web SDK and Form filling SDK both embed Suki's hosted Form filling UI. Use the Web SDK path when you already use `@suki-sdk/js` or `@suki-sdk/react`. Use the standalone packages (`@suki-sdk/form-filling` or `@suki-sdk/form-filling-react`) when you want Form filling without the rest of the Web SDK. Refer to [Form filling SDK installation](/form-filling-sdk/installation) for setup details. Do not have credentials yet? Complete the following steps: * Complete [Partner onboarding](/documentation/get-started/partner-onboarding). * Then [Partner authentication](/documentation/how-to/partner-authentication) to get an `sdp_suki_token`. * Staging base URL for API examples: `https://sdp.suki-stage.com` or ask your Suki representative for the staging base URL. ### Verify your first Form filling workflow Before you design the full production workflow, confirm that your staging integration can complete the Form filling path for the product you chose: * Authenticate successfully for your chosen product. * Start Form filling for a visit with at least one Medical form template in scope. * Capture visit conversation. * Receive structured form output after processing. * Show generated values in your review UI, or confirm they appear in the Form filling SDK experience. * Let a provider edit or confirm values, then save them in your application. After you have verified that your Form filling path works end to end, continue with template selection, review UX, and rollout measurement for production. ## How Form filling workflows work Across both modalities, the clinician workflow for Form filling is the same. The only difference is who owns each step. Refer to the table below to see who owns each step for each modality. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} flowchart LR A[Select medical
form templates] --> B[Start Form filling
for the visit] B --> C[Capture visit
conversation] C --> D[Suki maps speech
to template fields] D --> E[Provider reviews
generated values] E --> F[Edit, validate,
and save to EHR] style A fill:#FFF394,stroke:#333,color:#000 style B fill:#FFF394,stroke:#333,color:#000 style C fill:#FFF394,stroke:#333,color:#000 style D fill:#FFF394,stroke:#333,color:#000 style E fill:#FFF394,stroke:#333,color:#000 style F fill:#FFF394,stroke:#333,color:#000 ``` | Step | Form filling SDK | Form filling APIs | | --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | | Start Form filling | SDK opens Suki's hosted UI | Your app creates the session and you need handle the UI and session lifecycle | | Choose templates | Clinician or your app config in the SDK | Your app seeds the template IDs in context using the `form_template_ids` context parameter | | Capture audio | Hosted UI handles capture | Your app streams audio on the Partner WebSocket | | Get structured output | Callbacks and optional webhooks | Your app polls status and retrieves structured data | | Review and save | Your app receives results and owns save | Your app owns review UI and EHR handoff | If you are building with our Partner APIs, follow [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage) for how to create a session, stream audio, end the session, and retrieve structured data. For Form filling APIs, the Form filling session ID is not the same value as an [Ambient clinical note session](/api-reference/ambient-sessions/create). Use only the ID returned from [Create Form filling session API](/form-filling-api-reference/form-filling-sessions/create). ## Decide before you build your workflow Before you pick Form filling APIs, Web SDK Form filling, or Form filling SDK for production, align on a few product decisions. Agree which Medical form templates are in scope, who owns capture and review UI, how results reach your server, and how Form filling relates to Ambient or Dictation if you offer more than one product. Those choices shape UX, integration timeline, and which Suki products you combine for a best-fit solution. Use the following sections to align your team. Be clear about **which forms** the visit must complete and **who** completes them. Common examples include nursing assessments, vitals, intake, medication review, and other template-bound workflows. Form filling returns structured values from [Suki Medical form templates](/documentation/concepts/form-filling/form-filling-templates). It does not generate an ambient clinical note. If you need a full clinical note from the visit conversation, use [Ambient clinical documentation](/documentation/concepts/ambient-clinical-notes/ambient-documentation). If you need exact wording in a free-text field, use [Dictation](/documentation/concepts/dictation/dictation). Start with one or two templates for the pilot. Binding every available template in one session makes review harder and slows your first success path. With Suki Form filling, you **capture conversation during the session** and **retrieve structured form output after the session ends**. Submit does not return completed form values immediately. Suki processes the audio, then your app receives structured data through status and retrieval APIs, SDK callbacks, or partner webhooks. Providers review generated field values when processing completes. Plan how you show uploading, processing, and timeout states in hosted UI or in your own review screens. For Form filling SDK offline submit, the hosted UI can show an uploading state until audio reaches Suki. Refer to [Session workflow](/form-filling-sdk/guides/integration-patterns). Product choice depends on how much UI you want Suki to own: * **Form filling APIs:** Your app owns session create, context, `/ws/stream` audio, status, structured data retrieval, review UI, and EHR save. Start with the [Form filling API quickstart](/form-filling-api-reference/quickstart). * **Web SDK Form filling:** Use this when you already use `@suki-sdk/js` or `@suki-sdk/react` at **v3.2.0** or later. Form filling comes from the Web SDK package. See [Web SDK Form filling](/web-sdk/form-filling-overview). * **Form filling SDK:** Use the standalone hosted UI packages when you want Form filling without the rest of the Web SDK. See [Form filling SDK quickstart](/form-filling-sdk/quickstart). Web SDK Form filling and Form filling SDK both embed Suki hosted Form filling UI. Pick one install path. Do not mix both package sets for the same screen without a clear reason. Decide whether each session binds one template or more than one. * **Single-form:** One `form_template_id` for a focused assessment. * **Multi-form:** More than one template in the same session. Hosted UI can show template selection when multiple templates are configured. Output quality depends on binding the right templates for the visit, not every template in the catalog. List templates from the [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates) Info API, then seed the IDs your workflow needs. Refer to [Session workflow](/form-filling-sdk/guides/integration-patterns) for single-form and multi-form hosted behavior. Clinicians remain the final authority on form values. Define how providers review generated fields, edit or complete empty fields, and approve the save. Decide: * Whether review happens in your EHR or custom UI after APIs return structured data, or after Form filling SDK / Web SDK callbacks. * What happens when a template returns no values: retry, enter fields manually, or leave them empty. * How you map results to the encounter. Pass a partner `correlation_id` so callbacks and webhooks can match the correct record. * How production delivery works. For Form filling SDK, register a [partner webhook](/documentation/webhook/overview). Do not rely on browser `onSubmit` alone if the tab can close before processing finishes. Structured responses include `generated_values` and `non_generated_values`. Plan review UX for both. You can also submit Form filling feedback with entity `AMBIENT_GENERATED_MEDICAL_FORM` when you collect ratings on generated forms. ## Design the clinician workflow After those decisions are clear, turn them into a Form filling workflow your team can build. Use this table to align on the answers. | Question | Example answer | Why it matters | | :------------------------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Which templates are in scope for this visit? | Vitals and Neuro only | Output quality depends on binding the right templates, not every available template. | | Single-form or multi-form? | Single-form for the pilot | Multi-form adds selection and review complexity. | | Is capture during the visit or after? | During the visit, in the Form filling session for that encounter | Form filling works best when conversation and form capture happen in the same Form filling session. Ending the session is not the same as closing the visit if another session will follow. | | Who owns the review UI? | Our EHR review screen for APIs | With APIs, you build review screens. With Form filling SDK or Web SDK Form filling, Suki owns more of the capture UI and you own save. | | What if a template returns no values? | Manual entry allowed | Avoid blocking chart close when conversation did not cover a field. | | How do production results reach your server? | Partner webhook plus `correlation_id` | Browser callbacks alone are not enough if the clinician closes the tab during processing. | | When is form data final? | After provider validate and save | Make save, validate, and EHR submit states explicit. | Across products, the path stays the same: select templates, start Form filling, capture conversation, process after the session ends, review structured values, then save to the EHR. See [How Form filling workflows work](#how-form-filling-workflows-work). ## How to implement Form filling Next, align on the following implementation choices. These choices decide which Form filling product you use, which templates you bind, and how structured results reach your systems. ### 1. Map the end-to-end Form filling workflow Walk the visit from template selection to saved form data. For each step, name who owns it: your app, Suki hosted UI, or your backend. Typical stages: 1. Select the Medical form templates for the encounter. 2. Create or open a Form filling session with those templates in context. 3. Capture the visit conversation. 4. End the Form filling session when that recording is finished, then wait for processing. 5. Retrieve or receive structured form output. 6. Let the provider review, edit, and save values into the EHR. Keep Form filling session IDs separate from Ambient clinical note session IDs. Use only the ID returned from [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create). ### 2. Choose your audio capture strategy Form filling quality depends on clear visit conversation and the correct session path. Pick the product that matches who should own the capture UI. | Capture path | Best for | What you own | Where to start | | :----------------------- | :----------------------------------------------------- | :---------------------------------------------------------------------------- | :-------------------------------------------------------------------- | | **Form filling SDK** | Hosted Form filling UI without the rest of the Web SDK | Encounter context, templates, `correlation_id`, callbacks, webhooks, EHR save | [Form filling SDK quickstart](/form-filling-sdk/quickstart) | | **Web SDK Form filling** | Apps already on Web SDK `v3.2.0+` | Same hosted Form filling flow from the Web SDK package | [Web SDK Form filling](/web-sdk/form-filling-overview) | | **Form filling APIs** | Custom UI and backend-owned streaming | Create session, context, `/ws/stream`, status, structured data, review UI | [Form filling API quickstart](/form-filling-api-reference/quickstart) | For Form filling APIs, stream visit audio on **`GET /ws/stream`** with the Form filling session ID. Use mono **LINEAR16 PCM** at **16 kHz**. Refer to [Audio capture best practices](/documentation/how-to/audio-streaming/audio-capture-best-practices) and [Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage). #### Design for clean Form filling audio Good audio is critical for Form filling quality. Capture clear visit conversation so Suki can map speech to template fields. Design your Form filling workflow so providers can: * Confirm that recording has started and stopped. * Know which templates are in scope for the session. * Review structured values while visit context is still fresh. * Retry or manually complete fields when a template returns no output. If you use **Form filling APIs**, your application owns the UI, audio streaming, review screens, and save logic. If you use the **Form filling SDK** or **Web SDK Form filling**, Suki provides the hosted Form filling experience, and your application owns callbacks, webhook handling, and EHR handoff. ### 3. Choose your template strategy Decide how many templates the first pilot needs and how you bind them. | Approach | What you configure | Best for | | :--------------------------- | :------------------------------------------------------------------- | :--------------------------------------------------------- | | **Single template** | One `form_template_id` in session context | Fast MVP and focused assessments | | **Multi-template session** | Multiple template IDs for one encounter | Visits that complete several related forms together | | **Catalog-driven selection** | List templates from the Info API, then bind the IDs your org enables | Partners that expose a template picker from Suki’s catalog | List available templates with [Suki Medical form templates](/form-filling-api-reference/info/suki-medical-form-templates). Understand field definitions before you build review UI. Refer to [Form filling templates](/documentation/concepts/form-filling/form-filling-templates). After processing, structured data can include `generated_values` and `non_generated_values`. Design review screens for both. ### 4. Pull context in and push structured results out Send the right encounter and template context into Suki, then send approved form values back into your clinical systems. **Pull context into the session** Seed session context with the templates and encounter details you need. Common inputs include: * One or more `form_template_id` values. * Patient and provider context your workflow requires. * Partner `correlation_id` so results map to the correct encounter record. **Push results after processing** After processing completes: * Retrieve structured data with Form filling APIs, or handle SDK `onSubmit` / background submit callbacks. * Register a [partner webhook](/documentation/webhook/overview) for production delivery when using Form filling SDK or when your backend must receive results if the browser closes. * Optionally retrieve session [recordings](/form-filling-api-reference/form-filling-content/recording) when your workflow needs them. * Save approved values into the EHR or downstream system after provider review. Choose write-back depth for the pilot: * **Deep embedding:** Hosted Form filling inside your web workflow, then server-side save. * **API write-back:** Your server retrieves structured data or webhook payloads and writes to the EHR. * **Lightweight handoff:** Provider confirms values in your UI while you validate template quality, then deepen write-back. ## Common integration patterns and use cases Design your Form filling integration around template-bound sessions and how structured values move into your clinical systems after processing. The following patterns show common ways to build Form filling workflows: Capture visit conversation during in-person encounters and retrieve structured form output for nursing and clinical workflows. Capture conversation in browser or API workflows used during virtual visits, then return structured form data into your documentation workflow. List templates, bind `form_template_id` values in session context, and retrieve `generated_values` after processing. Own session lifecycle, audio streaming, structured data retrieval, and EHR handoff end to end with Partner APIs. ## Measure success for Form filling Treat measurement as something you own. Define what **better** and **worse** means for your Form filling workflow, track it where the work happens (your app + EHR), and use the findings before and after you deploy Form filling in production. | Metric type | Examples you can track | What it tells you | | --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------ | | **Time** | Time to complete assessments, time from session end to saved form | Whether Form filling reduces manual form entry | | **Completeness** | Share of templates with generated values, fields still empty after review | Whether conversation covered the expected form content | | **Quality and trust** | Fields edited before save, values rejected by clinicians | Whether providers trust the structured output | | **Rework** | Forms returned for correction, manual overrides, repeat sessions | Whether output needs too much cleanup | | **Reliability** | Session failures, missing structured data, callback or webhook failures | Whether the integration is stable in production | | **Adoption** | Sessions per clinician, templates used per visit, % of eligible visits | Whether Form filling is used in real workflows | Start with a small set of metrics, for example time to saved form, percent of templates with generated values, and later add more metrics as you deploy Form filling in production. ## Next steps **[Form filling basic usage](/documentation/how-to/form-filling/form-filling-basic-usage)** - Create a session, stream audio, end the session, and retrieve structured data. **[Form filling API quickstart](/form-filling-api-reference/quickstart)** - Build Form filling with Partner APIs when you own the full pipeline. **[Web SDK installation](/web-sdk/installation)** - Import Form filling from `@suki-sdk/js` or `@suki-sdk/react` when you already use the Web SDK. **[Form filling SDK quickstart](/form-filling-sdk/quickstart)** - Embed the hosted Form filling experience without the rest of the Web SDK. **[Form filling templates](/documentation/concepts/form-filling/form-filling-templates)** - Choose the Medical form templates for your workflow. **[Partner authentication](/documentation/how-to/partner-authentication)** - Get an `sdp_suki_token` for API and SDK calls.