Form Filling

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

​

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. If you are building with our Partner APIs, follow Form filling basic usage for how to create a session, stream audio, end the session, and retrieve structured data.

​

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.

​

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

​

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. 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 and 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. List available templates with Suki Medical form templates. Understand field definitions before you build review UI. Refer to 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 for production delivery when using Form filling SDK or when your backend must receive results if the browser closes.
• Optionally retrieve session recordings 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:

​

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. 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 - Create a session, stream audio, end the session, and retrieve structured data. Form filling API quickstart - Build Form filling with Partner APIs when you own the full pipeline. 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 - Embed the hosted Form filling experience without the rest of the Web SDK. Form filling templates - Choose the Medical form templates for your workflow. Partner authentication - Get an sdp_suki_token for API and SDK calls.