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

# Create form

> Create a service form. Requires a SERVER API key. The form is created with source INTERNAL and becomes available through GET /review-forms/{id} when its status is ACTIVE. Field and ticket automation rules match the dashboard editor.



## OpenAPI

````yaml POST /review-forms
openapi: 3.0.1
info:
  title: Masivo's REST API
  description: Learn how to use Masivo's REST API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.masivo.ai/api/storefront/v1
security:
  - bearerAuth: []
paths:
  /review-forms:
    post:
      description: >-
        Create a service form. Requires a SERVER API key. The form is created
        with source INTERNAL and becomes available through GET
        /review-forms/{id} when its status is ACTIVE. Field and ticket
        automation rules match the dashboard editor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewFormInsert'
            example:
              name: Post trip rating
              description: Post-trip satisfaction survey
              type: RATING
              fields:
                - name: score
                  label: Rating
                  type: SCORE
                  required: true
                  min: 1
                  max: 5
                - name: reason
                  label: What went wrong?
                  type: MULTI_SELECT
                  required: false
                  options:
                    - label: Wait time
                      value: wait_time
                    - label: Service
                      value: service
                      requires_comment: true
                - name: comment
                  label: Comment
                  type: TEXT
                  required: false
              settings:
                ticket_automation:
                  enabled: true
                  pipeline_id: 550e8400-e29b-41d4-a716-446655440000
                  priority: high
                  trigger: conditions
                  conditions:
                    - - primitive: custom
                        type: Response answer
                        reporting_period: MONTHLY
                        field: score
                        operator: less than
                        value: '3'
      responses:
        '201':
          description: Service form created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ReviewForm'
        '403':
          description: CLIENT API keys cannot create service forms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid request body, duplicated name, or unknown ticket pipeline
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    example: Service form names must be unique.
components:
  schemas:
    ReviewFormInsert:
      type: object
      required:
        - name
        - type
        - fields
      properties:
        name:
          type: string
          maxLength: 120
          description: Unique per account (case insensitive) among non-deleted forms
        description:
          type: string
          maxLength: 500
          nullable: true
        type:
          $ref: '#/components/schemas/FormType'
        status:
          allOf:
            - $ref: '#/components/schemas/FormStatus'
          default: ACTIVE
        fields:
          type: array
          minItems: 1
          maxItems: 30
          description: >-
            Field names must be unique. SELECT and MULTI_SELECT need at least
            one option. SCORE max must be greater than min (defaults 1 and 5).
            If an option sets requires_comment, the form must include a TEXT
            field.
          items:
            $ref: '#/components/schemas/FormField'
        settings:
          type: object
          additionalProperties: true
          default: {}
          properties:
            ticket_automation:
              $ref: '#/components/schemas/ReviewFormTicketAutomation'
    ReviewForm:
      type: object
      required:
        - id
        - name
        - type
        - status
        - fields
        - settings
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          $ref: '#/components/schemas/FormType'
        status:
          $ref: '#/components/schemas/FormStatus'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FormField'
        settings:
          type: object
          additionalProperties: true
          properties:
            ticket_automation:
              $ref: '#/components/schemas/ReviewFormTicketAutomation'
    Error:
      required:
        - error
        - details
      type: object
      properties:
        error:
          type: string
        details:
          type: string
    FormType:
      type: string
      enum:
        - RATING
        - COMMENT
        - THREAD
        - CUSTOM
    FormStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
    FormField:
      type: object
      required:
        - name
        - label
        - type
        - required
      properties:
        name:
          type: string
          description: API key used in answers
          example: score
        label:
          type: string
          example: Rating
        type:
          $ref: '#/components/schemas/FormFieldType'
        required:
          type: boolean
        options:
          type: array
          items:
            $ref: '#/components/schemas/FormFieldOption'
        images:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/FormFieldImage'
        min:
          type: integer
          example: 1
        max:
          type: integer
          example: 5
    ReviewFormTicketAutomation:
      type: object
      description: >-
        Opens a ticket from the responses submitted to this service form. The
        ticket is routed to the available agent with the lightest load.
      required:
        - enabled
      properties:
        enabled:
          type: boolean
          default: false
        pipeline_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Pipeline for the generated tickets. Required when enabled and must
            belong to the same account.
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - urgent
          default: medium
        trigger:
          type: string
          enum:
            - always
            - conditions
          default: always
          description: >-
            always opens a ticket for every response. conditions only opens one
            when the rule set matches.
        conditions:
          type: array
          description: >-
            Groups of conditions. Every condition inside a group must match
            (AND) and any matching group opens the ticket (OR). Conditions that
            read the AI analysis are evaluated once the response has been
            analyzed.
          items:
            type: array
            items:
              $ref: '#/components/schemas/ReviewFormTicketCondition'
    FormFieldType:
      type: string
      enum:
        - SCORE
        - TEXT
        - SELECT
        - MULTI_SELECT
    FormFieldOption:
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
          example: Wait time
        value:
          type: string
          example: wait_time
    FormFieldImage:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Public URL from the account multimedia library
        alt:
          type: string
          nullable: true
          example: Store front
    ReviewFormTicketCondition:
      type: object
      description: Condition evaluated before opening a ticket from a response.
      required:
        - primitive
        - type
        - reporting_period
        - operator
        - value
      properties:
        primitive:
          type: string
          enum:
            - custom
        type:
          type: string
          enum:
            - Response answer
            - Response sentiment score
            - Response emotion
            - Response risk flag
          description: >-
            Response answer reads a submitted field. The remaining types read
            the AI analysis of the response.
        reporting_period:
          type: string
          enum:
            - MONTHLY
            - QUARTERLY
            - SEMESTERLY
            - YEARLY
          example: MONTHLY
        field:
          type: string
          description: Answer name to evaluate. Required when type is Response answer.
        operator:
          type: string
          enum:
            - is
            - is not
            - equal to
            - not equal to
            - contains
            - starts with
            - ends with
            - greater than
            - greater than or equal to
            - less than
            - less than or equal to
        value:
          type: string
          description: >-
            Value to compare against: an answer value, a sentiment score from 0
            to 100, an analysis tag, or a risk flag.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.