---
title: "Create a form (optionally publish it)"
method: POST
path: "/api/v1/forms"
tags: ["Forms"]
---

# Create a form (optionally publish it)

`POST /api/v1/forms`

## Request

- Base URL: `https://api.formbuilder.com`
- URL: `https://api.formbuilder.com/api/v1/forms`
- Auth: HTTP bearer

Requires the forms:write scope. Set publish=true to publish immediately; the form goes through FormBuilder's safety review and may be held (see publish_blocked_reasons). Free plan allows 5 forms.

## Request body

- object
  - `title` string, required
  - `description` string
  - `submit_button_text` string
  - `publish` boolean
  - `fields` FieldInput[], required
    - `label` string, required
    - `type` 'text' | 'email' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'number' | 'date' | 'phone' | 'url' | 'file' | 'rating' | 'signature' | 'nps' | 'matrix' | 'ranking' | 'score' | 'calculation' | 'payment'
    - `required` boolean
    - `placeholder` string
    - `options` string[]: For select / radio / checkbox / multiselect
    - `page` integer

## Response `201`

Created

- object
  - `id` string
  - `title` string
  - `slug` string
  - `status` 'draft' | 'published'
  - `public_url` string, nullable: Live form URL when published
  - `edit_url` string
  - `publish_blocked_reasons` string[], nullable
  - `fields` integer

## Other responses

- `400`: Error
- `402`: Error

---

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