> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a form definition (to render the form)

> Returns the active form (fields, settings, localized content) plus company branding, ready to render in your own UI. Accepts the publishable capture key or the secret key.



## OpenAPI

````yaml /openapi-v1.json get /v1/forms/{id}
openapi: 3.0.3
info:
  title: Woku Client API v1
  description: >-
    Public Woku Client API. Switch the version selector at the top to view the
    v0 reference.


    This spec covers:

    - **Wokus** — create wokus, fetch review data, submit text/voice reviews,
    share by email.

    - **Companies** — `GET /companies/me` returns the caller company.

    - **Reports** — company-wide and per-tool NPS reports.

    - **External Trackers** — tag your Wokus with identifiers from third-party
    systems (CRM transaction id, ERP order id, etc.) and look them up later.


    ## Authentication


    All endpoints require a Bearer token in the `Authorization` header. Obtain
    your company API key from the Woku dashboard.


    ```

    Authorization: Bearer your_api_key_here

    ```


    ## Base URL


    Production: `https://clientapi.woku.app`


    ## Model (External Trackers)


    - **Tracker definition** (`ExternalTracker`): a per-company catalog entry
    like `{ name: 'trr', system: 'crm interno', description: '...' }`. Defined
    by an admin in the Woku dashboard.

    - **Tracker value** (`WokuExternalTrackerValue`): a string value bound to a
    (Woku, Tracker) pair. Multiple Wokus may share the same value.
  version: 1.0.0
  contact:
    name: Woku Support
    url: https://woku.app
    email: team@woku.app
servers:
  - url: https://clientapi.woku.app
    description: Production server
security: []
tags:
  - name: Wokus
    description: >-
      Create wokus, fetch review data, submit text and voice reviews, share
      review links by email.
  - name: Companies
    description: Caller-company endpoint.
  - name: Reports
    description: NPS reports for the caller company and individual NPS tools.
  - name: NPS
    description: >-
      Capture NPS scores (company-level or per NPS tool) and fetch NPS tool
      definitions.
  - name: CSAT
    description: >-
      Capture CSAT (1-5 satisfaction) scores company-level or per CSAT tool,
      fetch tool definitions and responses, and submit text and voice feedback.
  - name: CES
    description: >-
      Capture CES (effort) scores company-level or per CES tool, fetch tool
      definitions and responses, and submit text and voice feedback.
  - name: External Trackers
    description: >-
      Tag Wokus with identifiers from external systems and look them up by name
      + value.
  - name: Quarantines
    description: >-
      Check whether a respondent is currently quarantined before prompting for
      feedback.
  - name: Invitations
    description: >-
      Survey distribution: send NPS surveys, forms and woku review invitations
      by email or WhatsApp.
  - name: Forms
    description: Fetch form definitions and submit responses from your own UI.
  - name: Flows
    description: Render flow journeys (ordered wokus with an optional NPS) in your own app.
  - name: Captures
    description: Mobile SDK capture ingestion
paths:
  /v1/forms/{id}:
    get:
      tags:
        - Forms
      summary: Get a form definition (to render the form)
      description: >-
        Returns the active form (fields, settings, localized content) plus
        company branding, ready to render in your own UI. Accepts the
        publishable capture key or the secret key.
      operationId: v1GetForm
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Form id
      responses:
        '200':
          description: Form definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1FormDefinitionResponse'
        '403':
          description: Invalid key, or the form does not belong to the caller company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Form not found or inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      security:
        - BearerAuth: []
        - PublishableKey: []
components:
  schemas:
    V1FormDefinitionResponse:
      type: object
      properties:
        form:
          type: object
          properties:
            _id:
              type: string
            name:
              type: string
            description:
              type: string
            fields:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  label:
                    type: string
                  type:
                    type: string
                    enum:
                      - text
                      - number
                      - date
                      - select
                      - multiselect
                      - email
                      - phone
                  required:
                    type: boolean
                  placeholder:
                    type: string
                  options:
                    type: array
                    items:
                      type: string
                  order:
                    type: number
            settings:
              type: object
            closed:
              type: boolean
            availableLocales:
              type: array
              items:
                type: string
            defaultLocale:
              type: string
            localizedContent:
              type: array
              items:
                type: object
        company:
          type: object
          properties:
            name:
              type: string
            avatar:
              type: string
    ForbiddenError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          type: string
          example: Authentication required
        error:
          type: string
          example: Forbidden
    NotFoundError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: External tracker not found
        error:
          type: string
          example: Not Found
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Company API key. Obtain this from your Woku dashboard under Settings >
        API Keys. The same key used for the v0 endpoints.
    PublishableKey:
      type: apiKey
      in: header
      name: x-woku-key
      description: >-
        Publishable capture key (pk_…), safe to embed in the public web widget.
        Accepted only on capture endpoints; scoped to capture (cannot create
        wokus, share, or read reports).

````