---
title: "Create a form"
method: POST
path: "/form/create/"
tags: ["Forms"]
---

# Create a form

`POST /form/create/`

## Request

- Base URL: `https://hovercode.com/api/v2`
- URL: `https://hovercode.com/api/v2/form/create/`
- Auth: API key in header `Authorization`

Creates a draft form. Add fields with save, then publish.

## Request body

- object
  - `workspace` string, uuid, required
  - `title` string, required
  - `description` string

## Response `201`

Form created.

- Form
  - `id` string, uuid, required
  - `workspace_id` string, uuid, nullable
  - `status` 'Draft' | 'Published' | 'Closed' | 'Deleted', required
  - `logo` string, uri, nullable
  - `title` string, required
  - `description` string, nullable
  - `bg_color` string: Hex color.
  - `text_color` string: Hex color.
  - `button_color` string: Hex color.
  - `button_text_color` string: Hex color.
  - `thank_you_title` string
  - `thank_you_message` string, nullable
  - `redirect_url` string, nullable
  - `redirect_delay` integer
  - `outcomes` object[], nullable
  - `show_progress` boolean
  - `allow_multiple_submissions` boolean
  - `show_powered_by` boolean
  - `notification_recipients` string[], nullable
  - `can_use_notifications` boolean
  - `can_use_file_uploads` boolean
  - `current_user_id` string, nullable
  - `current_user_email_verified` boolean
  - `current_user_email` string, nullable
  - `fields` FormField[], required
    - `id` string, uuid, required
    - `field_type` 'text' | 'email' | 'phone' | 'number' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'date' | 'time' | 'url' | 'rating' | 'scale' | 'yes_no' | 'image' | 'image_choice' | 'ranking' | 'statement' | 'hidden' | 'page_break', required
    - `label` string, required
    - `placeholder` string, nullable
    - `help_text` string, nullable
    - `required` boolean
    - `min_length` integer, nullable
    - `max_length` integer, nullable
    - `min_value` number, nullable
    - `max_value` number, nullable
    - `pattern` string, nullable
    - `options` FormFieldOption[], nullable: For `select`/`radio`/`checkbox`.
      - `value` unknown
      - `label` string
    - `logic` object, nullable: Conditional logic rules.
    - `settings` object, nullable
      - `min_label` string
      - `max_label` string
      - `allow_other` boolean
      - `randomize` boolean
    - `order` integer, required
  - `shortlink_url` string, uri, nullable
  - `shortlink_domain` string, nullable
  - `shortlink_slug` string, nullable
  - `response_count` integer
  - `has_unpublished_changes` boolean
  - `qr_code_svg` string, nullable: Null until published.
  - `qr_id` string, uuid, nullable
  - `share_url` string, uri, nullable: Public respondent link; null unless the form is Published.
  - `dashboard_url` string, uri
  - `can_remove_powered_by` boolean
  - `created` string, date-time
  - `modified` string, date-time

## Other responses

- `400`: Validation error.
- `401`: Missing or invalid API token.
- `403`: Not permitted: plan limit or paid feature, or (on form endpoints) a missing or invalid token.
- `404`: Not found, or not in a workspace you belong to.
- `415`: Request body was not JSON.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds before retrying.

---

[API](https://skmtc.dev/hovercode/apis/hovercode-api.md) · [All operations](https://skmtc.dev/hovercode/apis/hovercode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hovercode/apis/hovercode-api/revisions/4a9bc3cafe41?raw)