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

# Ambient Workflows - Integration Decision Guide

> Compare Direct APIs, Web SDK, Headless Web SDK, and Mobile SDK to select the right integration method for your healthcare application

Suki for Partners provides different integration paths for adding ambient clinical documentation and dictation capabilities to your application.
Each integration path is designed for different product requirements, implementation approaches, and levels of UI ownership.

This guide explains the available integration options for ambient and dictation workflows and helps you select the approach that best fits your application architecture, technology stack, and user experience goals.
Use this guide to understand the tradeoffs between each integration path, including how much workflow logic, audio handling, and UI customization your team manages.

For Form filling workflows, refer to the [Form Filling integration decision guide](/documentation/form-filling-integration-decision-guide).

## Integration options

### Ambient APIs

Ambient APIs are the most flexible integration option and allow you to build your own user interface and authentication flow for your application.

<CardGroup cols={2}>
  <Card title="Recommended for:" icon="server">
    • Backend systems and server integrations\
    • Custom user interfaces on any stack\
    • Multi-platform applications
  </Card>

  <Card title="What you build:" icon="gear">
    • Complete user interface\
    • Authentication flow\
    • Audio handling and API/WebSocket usage
  </Card>
</CardGroup>

### Web SDK

The Web SDK delivers pre-built clinical UI components and handles authentication and audio processing for browser-based healthcare applications.

<CardGroup cols={2}>
  <Card title="Recommended for:" icon="cube">
    • Web-based healthcare applications\
    • Browser-based EHR integrations\
    • Teams that want pre-built clinical UI
  </Card>

  <Card title="What's provided:" icon="gear">
    • Pre-built UI components\
    • Authentication handling\
    • Audio processing
  </Card>
</CardGroup>

### Headless Web SDK

The Headless Web SDK provides React hooks for authentication and ambient sessions while you build a fully custom interface.

<CardGroup cols={2}>
  <Card title="Recommended for:" icon="react">
    • React web applications (React 18+)\
    • Custom UI that matches your design system\
    • Full control over recording controls, status, and layout
  </Card>

  <Card title="What's provided:" icon="gear">
    • React hooks for auth and ambient sessions\
    • Core ambient, streaming, and session behavior\
    • No pre-built clinical UI (you build the interface)
  </Card>
</CardGroup>

### Mobile SDK

The Mobile SDK offers native iOS integration for ambient workflows on mobile devices.

<CardGroup cols={2}>
  <Card title="Recommended for:" icon="mobile">
    • Native iOS applications\
    • Mobile healthcare apps\
    • Apps requiring native device features
  </Card>

  <Card title="Platform support:" icon="gear">
    • iOS (available now)\
    • Android (in development)
  </Card>
</CardGroup>

### Dictation

The Dictation SDK embeds hosted dictation in your web application via iframe and JavaScript or React packages.

<CardGroup cols={2}>
  <Card title="Recommended for:" icon="microphone">
    • Web applications that need dictation\
    • Frontend systems that need dictation
  </Card>

  <Card title="What's provided:" icon="gear">
    • Hosted iframe for dictation\
    • In-field and scratchpad modes\
    • JavaScript and React packages
  </Card>
</CardGroup>

## How to choose

<Tabs>
  <Tab title="By Project Type">
    <AccordionGroup>
      <Accordion title="Web-based Healthcare Application">
        **Choose Web SDK if:**

        * You want pre-built clinical UI components
        * You prefer the fastest path to a browser-based integration with Suki-provided UI

        **Choose Headless Web SDK if:**

        * You use React 18 or higher and want hooks for auth, sessions, and recording
        * You need a custom interface, branding, or workflows that pre-built components do not cover
        * You want SDK-managed session and audio behavior while owning all presentation

        **Choose Direct APIs if:**

        * Your client is not React, or you integrate from multiple client types against the same API surface
        * You want full control at the REST/WebSocket level without an SDK on the web client
      </Accordion>

      <Accordion title="Mobile Healthcare Application">
        **For iOS Applications:**

        * **Choose Mobile SDK** - provides native iOS functionality and device integration

        **For Android Applications:**

        * **Choose Direct APIs** - Mobile SDK for Android is currently in development
      </Accordion>

      <Accordion title="Backend System or Server Integration">
        **Choose Direct APIs**

        * This is your only option for server-to-server integrations
        * Provides complete control over data processing and system integration
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="By Team Skills">
    <CardGroup cols={2}>
      <Card title="Frontend/React Experience">
        **Recommended: Web SDK or Headless Web SDK**

        Use **Web SDK** for pre-built UI and speed. Use **Headless Web SDK** when you will build custom UI in React with hooks.
      </Card>

      <Card title="Backend/API Experience">
        **Recommended: Direct APIs**

        Full control and leverages existing API development skills
      </Card>

      <Card title="iOS/Swift Experience">
        **Recommended: Mobile SDK**

        Native iOS functionality with SDK support and familiar development patterns
      </Card>

      <Card title="Limited Development Resources">
        **Recommended: Web SDK**

        Requires minimal custom UI work with ready-to-use components
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="By Requirements">
    | Your Need                                    | Recommended Choice | Why                                                        |
    | -------------------------------------------- | ------------------ | ---------------------------------------------------------- |
    | **Quick integration in the browser**         | Web SDK            | Ready-to-use components, minimal setup                     |
    | **Custom web UI in React**                   | Headless Web SDK   | Hooks for platform behavior; you own layout and components |
    | **Custom UI/UX without React on the web**    | Direct APIs        | Use your stack and patterns against the API                |
    | **Native mobile features (iOS)**             | Mobile SDK         | Native device integration and performance                  |
    | **Multi-platform support**                   | Direct APIs        | Same API surface across web, mobile, and backend           |
    | **Complete UX control (any client)**         | Direct APIs        | Build exactly what you need at the protocol level          |
    | **Proven clinical workflows in the browser** | Web SDK            | Pre-built healthcare interface patterns                    |
  </Tab>
</Tabs>

<Note>
  **HIPAA Compliance**: All integration methods can be implemented in a HIPAA-compliant manner. Compliance depends on your implementation practices and security measures.
</Note>

## Prerequisites for all integration methods

Before integrating with any Suki Platform method, you must complete the partner onboarding process:

### Required for all integration methods

**Partner Registration:**

* Complete the [Partner onboarding process](/documentation/partner-onboarding)
* Receive your unique `partner_id` from Suki
* Provide your JWKS endpoint URL to Suki for token validation

**Authentication System:**

* OAuth 2.0 compliant authentication system
* JWT token generation with consistent user identifier
* Publicly accessible JWKS endpoint for token verification

### Additional requirements by method

**Web SDK:**

* ES6+ compatible browsers
* Host URLs whitelisted with Suki for SDK embedding

**Headless Web SDK:**

* React 18.0 or higher
* ES6+ compatible browsers
* Host URLs for your test and production apps provided to Suki for allowlisting (see [Headless Web SDK prerequisites](/headless-web-sdk/prerequisites))

**Mobile SDK (iOS):**

* iOS 14.0 or later
* Xcode development environment
* Audio recording permissions in your app

**Ambient APIs:**

* WebSocket client implementation capability
* HTTPS/TLS support for secure API communication

**Dictation SDK:**

* ES6+ compatible browsers
* Host URLs for your test and production apps provided to Suki for allowlisting (see [Dictation SDK prerequisites](/dictation-sdk/prerequisites))

## Integration scenarios

<Tabs>
  <Tab title="Web Applications">
    <AccordionGroup>
      <Accordion title="EHR Integration">
        **Scenario:** Existing web-based Electronic Health Record system needing ambient clinical documentation

        **Recommended: Web SDK**

        • Integrates directly into your existing web application\
        • Provides pre-built clinical note interface\
        • Handles audio streaming and note generation automatically
      </Accordion>

      <Accordion title="Patient Portal">
        **Scenario:** Healthcare patient portal where providers can document encounters during telehealth visits

        **Recommended: Web SDK**

        • Ready-to-use telehealth documentation interface\
        • Built-in audio processing for web browsers\
        • Seamless integration with existing patient management systems
      </Accordion>

      <Accordion title="Custom-branded web documentation experience">
        **Scenario:** Web EHR or clinician workflow where ambient capture must match your design system, layout, and interaction patterns

        **Recommended: Headless Web SDK** (React 18+)

        • React hooks for authentication, session lifecycle, and recording control\
        • You implement controls, status, and note presentation\
        • Same core ambient capabilities as the Web SDK without pre-built clinical UI

        If you are not on React, use **Direct APIs** for an equivalent level of UI ownership.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Mobile Applications">
    <AccordionGroup>
      <Accordion title="iOS Telehealth App">
        **Scenario:** Native iOS application for remote patient consultations with clinical note capture during video calls

        **Recommended: Mobile SDK**

        • Native iOS performance and device integration\
        • Works with your existing iOS app architecture\
        • Provides offline functionality for unreliable network conditions
      </Accordion>

      <Accordion title="Android Healthcare App">
        **Scenario:** Native Android application for clinical documentation

        **Recommended: Direct APIs**

        • Custom implementation using Direct APIs\
        • Full control over Android user experience\
        • Mobile SDK for Android currently in development
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Backend Systems">
    <AccordionGroup>
      <Accordion title="Data Processing System">
        **Scenario:** Batch processing of clinical audio files or integration with existing backend workflow systems

        **Recommended: Direct APIs**

        • Server-to-server integration capability\
        • Complete control over data processing workflows\
        • Integration with existing backend systems and databases
      </Accordion>

      <Accordion title="Multi-platform Healthcare Suite">
        **Scenario:** Healthcare applications spanning web browsers, mobile devices, and backend systems

        **Recommended: Direct APIs**

        • Single integration approach works across all platforms\
        • Complete control over user experience on each platform\
        • Consistent API interface regardless of client type
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Next steps

To begin your integration, review the documentation for your chosen approach:

<CardGroup cols={2}>
  <Card title="Web SDK Quickstart" href="/web-sdk/quickstart" arrow={true} icon="list">
    Get started with pre-built components and fast integration
  </Card>

  <Card title="Headless Web SDK Quickstart" href="/headless-web-sdk/quickstart" arrow={true} icon="list">
    React hooks, custom UI, and ambient sessions in your application
  </Card>

  <Card title="API Overview" href="/api-reference/overview" arrow={true} icon="list">
    Build custom integrations with maximum flexibility
  </Card>

  <Card title="Mobile SDK Overview" href="/mobile-sdk/overview" arrow={true} icon="list">
    Native iOS integration for mobile applications
  </Card>

  <Card title="Dictation SDK Overview" href="/dictation-sdk/introduction" arrow={true} icon="list">
    Hosted dictation in your web application
  </Card>

  <Card title="Partner Onboarding" href="/documentation/partner-onboarding" arrow={true} icon="list">
    Start your integration journey with Suki
  </Card>
</CardGroup>

## Get personalized integration guidance

If your use case doesn't clearly match the scenarios above, or you need specific technical advice for your healthcare application, our customer success team provides personalized consultation.

**Before contacting support or sales, prepare:**

* Description of your healthcare application and clinical workflows
* Target platform (web with React or not, iOS, Android, backend system)
* Development timeline and resource constraints
* Specific technical requirements or compliance needs

**Contact options:**

* **Technical consultation**: [Schedule a call with our integration team](https://www.suki.ai/suki-partners/)
* **Development support**: [support@suki.ai](mailto:support@suki.ai)
* **Community discussions**: [Contact us for community access](https://www.suki.ai/contact-us/)