Create a form

​

Creates a form. Only title is required, a form may start empty and gain fields later. New forms default to draft status (not publicly visible). Set status: "published" to accept submissions immediately. A slug, if given, must be unique for your account. Send an Idempotency-Key header to make retries safe: a repeat with the same key returns the originally created form instead of a duplicate.

Body·
required
application/json

The form to create.

Payload for creating a new form. Only title is required; a form may start with no fields and have them added later.

  • title
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Form title, shown as the heading on the public form page.

  • description
    Type: string
    max length:  
    2000

    Optional longer description shown beneath the title on the public form page.

  • fields
    Type: array · …100

    Ordered list of a form’s fields (max 100). Field keys must be unique within the form. The order here is the order fields render on the public page.

  • slug
    Type: string
    min length:  
    2
    max length:  
    64    Pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$

    Optional human-friendly URL segment for the public form (/f/{slug}). Lowercase alphanumeric with dashes; must be unique per owner. The form’s id always works as a URL even without a slug.

  • status
    Type: string enum

    Lifecycle state. draft forms are private (not publicly viewable or submittable); published forms accept public submissions; closed forms are viewable but reject new submissions.

    values
    • draft
    • published
    • closed
Responses
  • application/json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
Request Example for post/v1/forms
ffforms forms create --title 'Contact us' --description 'Questions, feedback, or partnership ideas. Send them our way.' --slug 'contact-us' --status 'draft'

{
  "id": "frm_3Qk9v2Xb7Lm",
  "slug": "contact-us",
  "title": "Contact us",
  "description": "Questions, feedback, or partnership ideas. Send them our way.",
  "status": "published",
  "fields": [
    {
      "key": "name",
      "type": "text",
      "label": "Your name",
      "required": true
    },
    {
      "key": "email",
      "type": "email",
      "label": "Email address",
      "required": true
    },
    {
      "key": "topic",
      "type": "select",
      "label": "Topic",
      "required": true,
      "options": [
        {
          "value": "sales",
          "label": "Sales"
        },
        {
          "value": "support",
          "label": "Support"
        }
      ]
    }
  ],
  "createdAt": "2026-07-28T10:15:30.000Z",
  "updatedAt": "2026-07-28T12:40:05.000Z"
}

The form was created.