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

# Suki Medical Form Templates

> List Suki-defined medical form templates available for Form filling sessions

Use this endpoint to get the list of Suki-defined medical form templates available for Form filling ambient sessions.

## Code examples

<Note>
  The code examples below use placeholders and the stage host `sdp.suki-stage.com` only as **examples**.
  For credentials, base URLs, where to run Python or TypeScript, CORS, and **cURL**, refer to [Using code examples in your integration](/api-reference/api-guidelines#using-code-examples-in-your-integration) in the **API Reference Guidelines**.
</Note>

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, TypedDict, cast

    import requests

    BASE_URL = "https://sdp.suki-stage.com"


    class MedicalFormTemplate(TypedDict, total=False):
        description: str
        name: str
        schema: Any
        template_id: str
        type: str


    class GetSukiFormTemplatesResponse(TypedDict):
        form_templates: list[MedicalFormTemplate]


    class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

        def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url


    def _get_expect_json_object(url: str, headers: dict[str, str], expect_status: int) -> dict[str, Any]:
        r = requests.get(url, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

        detail = ""
        try:
            err = r.json()
            if isinstance(err, dict) and isinstance(err.get("message"), str):
                detail = err["message"]
        except ValueError:
            detail = (r.text or "")[:500]
        raise ApiHttpError(r.status_code, url, detail or "(no body)")


    def get_suki_medical_form_templates(suki_token: str) -> GetSukiFormTemplatesResponse:
        """GET /api/v1/info/suki-medical-form-templates (sdp_suki_token header required). HTTP 200."""
        url = f"{BASE_URL}/api/v1/info/suki-medical-form-templates"
        data = _get_expect_json_object(url, {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>"}, 200)
        ft = data.get("form_templates")
        if not isinstance(ft, list):
            raise ValueError(f"{url}: 200 response missing form_templates array")
        return cast(GetSukiFormTemplatesResponse, {"form_templates": ft})


    if __name__ == "__main__":
        try:
            out = get_suki_medical_form_templates("YOUR_SUKI_TOKEN")
            print(len(out["form_templates"]))
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

    type MedicalFormTemplate = {
      description?: string;
      name?: string;
      schema?: unknown;
      template_id?: string;
      type?: string;
    };

    type GetSukiFormTemplatesResponse = {
      form_templates: MedicalFormTemplate[];
    };

    class ApiHttpError extends Error {
      status: number;
      url: string;
      constructor(status: number, url: string, detail: string) {
        super(`HTTP ${status} ${url}: ${detail}`);
        this.status = status;
        this.url = url;
      }
    }

    async function getExpectJsonObject(url: string, headers: Record<string, string>, expectStatus: number) {
      const res = await fetch(url, { method: "GET", headers });
      const text = await res.text();
      const json = text ? JSON.parse(text) : {};

      if (res.status !== expectStatus) {
        const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)";
        throw new ApiHttpError(res.status, url, msg);
      }
      if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
      throw new ApiHttpError(res.status, url, "response JSON was not an object");
    }

    export async function getSukiMedicalFormTemplates(sukiToken: string): Promise<GetSukiFormTemplatesResponse> {
      const url = `${BASE_URL}/api/v1/info/suki-medical-form-templates`;
      const data = await getExpectJsonObject(url, { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>" }, 200);
      const ft = data.form_templates;
      if (!Array.isArray(ft)) {
        throw new Error(`${url}: 200 response missing form_templates array`);
      }
      return { form_templates: ft as MedicalFormTemplate[] };
    }

    // Example usage
    const out = await getSukiMedicalFormTemplates("YOUR_SUKI_TOKEN");
    console.log(out.form_templates.length);
    ```
  </Tab>
</Tabs>

<Note>
  If this endpoint returns an empty list, contact [support](mailto:support@suki.ai).
</Note>


## OpenAPI

````yaml GET /api/v1/info/suki-medical-form-templates
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, and reference metadata
    endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/info/suki-medical-form-templates:
    get:
      tags:
        - /api/v1/info
      summary: Get Suki medical form templates
      description: >-
        Returns Suki-defined medical form templates. Use each template's
        `template_id` as `form_template_id` when seeding or updating
        form-filling session context.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.GetSukiFormTemplatesResponse'
              example:
                form_templates:
                  - description: Standard vitals collection template for adult patients.
                    name: Adult Vitals
                    template_id: 019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0
                    type: VITALS_ASSESSMENT
                    schema:
                      items:
                        - code: Q003
                          id: respiratory_pattern
                          kind: field
                          options:
                            - code: null
                              display: Regular
                            - code: null
                              display: Shallow
                          pattern: ''
                          question: Respiratory Pattern / Effort
                          type: radio
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '403':
          description: Forbidden. The authenticated user cannot access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ForbiddenError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request GET \
              --url https://sdp.suki.ai/api/v1/info/suki-medical-form-templates \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** - Stable identifier for the active provider. Omit for
        standard partners whose `partner_token` identifies the user.
        **Required** for Bearer partners and Single Auth Token authentication
        where multiple providers share one `partner_token`. Use the same
        `provider_id` you sent on Login or Register.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.GetSukiFormTemplatesResponse:
      description: Response body for the /info/suki-medical-form-templates endpoint
      type: object
      properties:
        form_templates:
          description: List of Suki-defined medical form templates
          type: array
          items:
            $ref: '#/components/schemas/controllers.MedicalFormTemplate'
    controllers.AuthenticationError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid token
          description: Human-readable description of the authentication failure.
      description: Error response when authentication fails.
    controllers.ForbiddenError:
      type: object
      properties:
        code:
          type: integer
          example: 403
          description: HTTP status code for the error.
        message:
          type: string
          example: forbidden
          description: Human-readable description of the authorization failure.
      description: Error response when the caller lacks permission.
    controllers.MedicalFormTemplate:
      description: Suki-defined medical form template
      type: object
      properties:
        description:
          description: '**Optional** - Free-text description'
          type: string
          example: Standard vitals collection template for adult patients.
        name:
          description: Human-readable template name
          type: string
          example: Adult Vitals
        schema:
          description: >-
            Template structure: an object with an `items` array of field
            definitions.
          allOf:
            - $ref: '#/components/schemas/controllers.MedicalFormTemplateSchema'
        template_id:
          description: Unique identifier for this template version
          type: string
          example: 019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0
        type:
          description: Type classification (e.g., VITALS_ASSESSMENT, SKIN_ASSESSMENT)
          type: string
          example: VITALS_ASSESSMENT
      example:
        description: Standard vitals collection template for adult patients.
        name: Adult Vitals
        template_id: 019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0
        type: VITALS_ASSESSMENT
        schema:
          items:
            - code: Q003
              id: respiratory_pattern
              kind: field
              options:
                - code: null
                  display: Regular
                - code: null
                  display: Shallow
                - code: null
                  display: Deep
                - code: null
                  display: Labored
                - code: null
                  display: Tachypneic (rapid breathing)
                - code: null
                  display: Bradypneic (slow breathing)
                - code: null
                  display: Irregular
                - code: null
                  display: Apneic (no spontaneous breathing)
              pattern: ''
              question: Respiratory Pattern / Effort
              type: radio
    controllers.MedicalFormTemplateSchema:
      description: >-
        Object describing the structure of a medical form template, including
        its field definitions.
      type: object
      properties:
        items:
          description: Ordered list of template fields and questions.
          type: array
          items:
            $ref: '#/components/schemas/controllers.MedicalFormTemplateSchemaItem'
    controllers.MedicalFormTemplateSchemaItem:
      description: >-
        A single field or question definition inside a medical form template
        schema.
      type: object
      properties:
        code:
          description: Question or field code.
          type: string
          example: Q003
        id:
          description: Stable field identifier within the template.
          type: string
          example: respiratory_pattern
        kind:
          description: Item kind (for example `field`).
          type: string
          example: field
        options:
          description: >-
            **Optional** - Choices for selection-style fields (for example
            `radio`).
          type: array
          items:
            $ref: '#/components/schemas/controllers.MedicalFormTemplateSchemaOption'
        pattern:
          description: '**Optional** - Validation pattern when applicable.'
          type: string
          example: ''
        question:
          description: Question or field label text.
          type: string
          example: Respiratory Pattern / Effort
        type:
          description: Input type (for example `radio`, `text`).
          type: string
          example: radio
    controllers.MedicalFormTemplateSchemaOption:
      description: >-
        Selectable option for a form template field (for example radio or
        dropdown choices).
      type: object
      properties:
        code:
          description: >-
            **Optional** - Option code when provided; may be null for
            display-only choices.
          type: string
          nullable: true
          example: null
        display:
          description: Human-readable option label shown in the form UI.
          type: string
          example: Regular
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token for the authenticated provider. Obtain this by calling
        Login or Register with a valid `partner_token`. Pass the `suki_token`
        value from the JSON response as the `sdp_suki_token` header on REST
        requests and non-browser WebSocket upgrades. Browser WebSocket clients
        pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
        one hour; call Login again to refresh.

````