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

# Create Form

> Create a new form; requires forms-write ability.

# Create Form

Create a new form within a workspace.

## Authentication & Scope

Requires a Personal Access Token with the `forms-write` ability.

## Request

```http theme={null}
POST /open/forms HTTP/1.1
Host: api.opnform.com
Content-Type: application/json
Authorization: Bearer <token>
```

### Body Parameters

| Field         | Type   | Required | Description                                            |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| workspace\_id | number | Yes      | ID of the workspace that will own the form.            |
| title         | string | Yes      | Human-readable title shown in the dashboard.           |
| visibility    | string | Yes      | One of `public`, `draft`, or `closed`.                 |
| language      | string | Yes      | Two-letter ISO language code (e.g. `en`).              |
| properties    | array  | Yes      | Array of form blocks (see `FormProperty` schema).      |
| …other fields | mixed  | No       | See the `Form` schema for the full list of attributes. |

Example request:

```json theme={null}
{
  "workspace_id": 1,
  "title": "Event Registration",
  "visibility": "public",
  "language": "en",
  "properties": [
    {
      "id": "field-1",
      "type": "short_text",
      "name": "First name",
      "required": true
    }
  ]
}
```

## Response

`201 Created` – Returns the full `Form` object.

```json theme={null}
{
  "id": 99,
  "slug": "event-registration",
  "title": "Event Registration",
  "visibility": "public",
  "properties": [...]
}
```

`403 Forbidden` – The token does not include the `forms-write` ability.


## OpenAPI

````yaml post /open/forms
openapi: 3.0.1
info:
  title: OpnForm API
  description: API for interacting with OpnForm, primarily used for Zapier integration
  version: 1.0.0
servers:
  - url: https://api.opnform.com
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: Create and manage workspaces.
  - name: Workspace Users
    description: Manage users within a workspace.
  - name: Forms
    description: Manage and retrieve forms.
  - name: Submissions
    description: Access and manage form submissions.
  - name: Integrations
    description: Manage form integrations (webhooks) via API.
  - name: Zapier
    description: Legacy endpoints for the Zapier integration.
paths:
  /open/forms:
    post:
      tags:
        - Forms
      summary: Create Form
      description: Create a new form; requires forms-write ability.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Form'
      responses:
        '201':
          description: Form created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
        '403':
          description: Forbidden – token lacks forms-write ability
      security:
        - bearerAuth: []
components:
  schemas:
    Form:
      type: object
      properties:
        id:
          type: number
          description: The unique identifier for the form.
          readOnly: true
        slug:
          type: string
          description: The URL-friendly slug for the form.
          readOnly: true
        workspace_id:
          type: number
          description: ID of the workspace that owns the form.
          writeOnly: true
        title:
          type: string
          description: The title of the form.
        visibility:
          type: string
          enum:
            - public
            - draft
            - closed
          description: The current visibility state of the form.
        tags:
          type: array
          items:
            type: string
          nullable: true
        language:
          type: string
          description: Two-letter ISO language code.
        custom_domain:
          type: string
          nullable: true
        theme:
          type: string
          enum:
            - default
            - simple
            - notion
        font_family:
          type: string
          nullable: true
        color:
          type: string
        dark_mode:
          type: string
          enum:
            - light
            - dark
            - auto
        width:
          type: string
          enum:
            - centered
            - full
        size:
          type: string
          enum:
            - sm
            - md
            - lg
        border_radius:
          type: string
          enum:
            - none
            - small
            - full
        layout_rtl:
          type: boolean
        uppercase_labels:
          type: boolean
        cover_picture:
          type: string
          format: uri
          nullable: true
        logo_picture:
          type: string
          format: uri
          nullable: true
        no_branding:
          type: boolean
          description: Whether to hide the OpnForm branding.
        transparent_background:
          type: boolean
          description: Transparent background when form is embedded.
        submit_button_text:
          type: string
          maxLength: 50
        submitted_text:
          type: string
          maxLength: 2000
        redirect_url:
          type: string
          format: uri
          nullable: true
        re_fillable:
          type: boolean
        re_fill_button_text:
          type: string
          maxLength: 50
        confetti_on_submission:
          type: boolean
        show_progress_bar:
          type: boolean
        closes_at:
          type: string
          format: date-time
          nullable: true
        closed_text:
          type: string
          nullable: true
        max_submissions_count:
          type: integer
          minimum: 1
          nullable: true
        max_submissions_reached_text:
          type: string
          nullable: true
        auto_save:
          type: boolean
        auto_focus:
          type: boolean
        enable_partial_submissions:
          type: boolean
        editable_submissions:
          type: boolean
        editable_submissions_button_text:
          type: string
          maxLength: 50
        password:
          type: string
          nullable: true
        use_captcha:
          type: boolean
        captcha_provider:
          type: string
          enum:
            - recaptcha
            - hcaptcha
        can_be_indexed:
          type: boolean
        seo_meta:
          type: object
          nullable: true
        custom_code:
          type: string
          nullable: true
        database_fields_update:
          type: array
          items: {}
          nullable: true
        properties:
          type: array
          description: An array of field and layout blocks that make up the form.
          items:
            $ref: '#/components/schemas/FormProperty'
    FormProperty:
      type: object
      description: A single field or layout block within a form.
      properties:
        id:
          type: string
          description: A unique identifier for the block.
          format: uuid
        type:
          type: string
          description: The type of block.
        name:
          type: string
          description: The label or name of the field.
        help:
          type: string
          description: Help text displayed with the field.
        hidden:
          type: boolean
          description: Whether the field is hidden from view.
        required:
          type: boolean
          description: Whether the field is required.
        placeholder:
          type: string
          description: Placeholder text for the input.
        width:
          type: string
          enum:
            - full
            - 1/2
            - 1/3
            - 2/3
            - 1/4
            - 3/4
          description: The width of the block in the form layout.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Personal Access Token
      x-bearer-scopemap:
        workspaces-read: Read access to workspaces
        workspaces-write: Write access to workspaces
        workspace-users-read: Read access to workspace users
        workspace-users-write: Write access to workspace users
        forms-read: Read access to forms
        forms-write: Write access to forms
        manage-integrations: Manage form integrations (webhooks)

````