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

# Forms

> Create, retrieve, update, and delete forms via the REST API.

Forms are the core resource in FormFlows.ai. Each form has a set of fields, a status, and accumulates submissions over time. The API lets you manage forms programmatically — useful for templating, bulk operations, or embedding form creation into your own product.

***

## List forms

`GET /forms`

Returns a paginated list of forms in your account.

### Query parameters

<ParamField query="limit" type="integer" default="20">
  Number of forms to return. Maximum `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from the previous response's `next_cursor`. Omit to start from the beginning.
</ParamField>

<ParamField query="status" type="string">
  Filter by form status. One of `draft`, `published`, or `archived`.
</ParamField>

### Response

<ResponseField name="data" type="object[]">
  Array of form objects.

  <Expandable title="Form object properties">
    <ResponseField name="id" type="string">
      Unique form identifier, prefixed with `frm_`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the form.
    </ResponseField>

    <ResponseField name="description" type="string">
      Optional description of the form's purpose.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `draft`, `published`, or `archived`.
    </ResponseField>

    <ResponseField name="submission_count" type="integer">
      Total number of submissions received.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the form was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the most recent update.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Pass this value as the `cursor` parameter to fetch the next page. `null` if there are no more results.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  `true` if additional pages exist.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url "https://api.formflows.ai/v1/forms?limit=10&status=published" \
    --header "Authorization: Bearer sk_live_your_api_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.formflows.ai/v1/forms",
      headers={"Authorization": "Bearer sk_live_your_api_key"},
      params={"limit": 10, "status": "published"},
  )

  result = response.json()
  for form in result["data"]:
      print(form["id"], form["name"])
  ```
</CodeGroup>

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "frm_8kQmP2xNvL",
      "name": "Customer Onboarding Survey",
      "description": "Collects new customer information after sign-up.",
      "status": "published",
      "submission_count": 342,
      "created_at": "2024-11-03T09:15:00Z",
      "updated_at": "2024-12-01T14:22:00Z"
    },
    {
      "id": "frm_3tRjW9hYsC",
      "name": "Product Feedback Form",
      "description": null,
      "status": "published",
      "submission_count": 87,
      "created_at": "2024-11-20T16:40:00Z",
      "updated_at": "2024-11-20T16:40:00Z"
    }
  ],
  "next_cursor": "cur_eyJpZCI6ImZybV8zIn0",
  "has_more": true
}
```

***

## Create a form

`POST /forms`

Creates a new form. Forms start in `draft` status by default.

### Body parameters

<ParamField body="name" type="string" required>
  Display name for the form. Maximum 200 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the form's purpose.
</ParamField>

<ParamField body="fields" type="object[]">
  Array of field definitions to include in the form.

  <Expandable title="Field object properties">
    <ParamField body="label" type="string" required>
      The field label shown to respondents.
    </ParamField>

    <ParamField body="type" type="string" required>
      Field type. One of `text`, `email`, `number`, `dropdown`, `checkbox`, `radio`, `textarea`, `file`, `date`.
    </ParamField>

    <ParamField body="required" type="boolean" default="false">
      Whether the field must be filled before the form can be submitted.
    </ParamField>

    <ParamField body="options" type="string[]">
      For `dropdown`, `checkbox`, and `radio` fields — the list of selectable options.
    </ParamField>

    <ParamField body="placeholder" type="string">
      Placeholder text shown inside the input.
    </ParamField>
  </Expandable>
</ParamField>

### Response

Returns the created form object, including the server-assigned `id`.

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url "https://api.formflows.ai/v1/forms" \
    --header "Authorization: Bearer sk_live_your_api_key" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Event Registration",
      "description": "Registration form for the 2025 annual conference.",
      "fields": [
        {
          "label": "Full name",
          "type": "text",
          "required": true,
          "placeholder": "Jane Smith"
        },
        {
          "label": "Email address",
          "type": "email",
          "required": true
        },
        {
          "label": "Which sessions will you attend?",
          "type": "checkbox",
          "options": ["Keynote", "Workshop A", "Workshop B", "Networking Lunch"]
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  payload = {
      "name": "Event Registration",
      "description": "Registration form for the 2025 annual conference.",
      "fields": [
          {"label": "Full name", "type": "text", "required": True, "placeholder": "Jane Smith"},
          {"label": "Email address", "type": "email", "required": True},
          {
              "label": "Which sessions will you attend?",
              "type": "checkbox",
              "options": ["Keynote", "Workshop A", "Workshop B", "Networking Lunch"],
          },
      ],
  }

  response = requests.post(
      "https://api.formflows.ai/v1/forms",
      headers={"Authorization": "Bearer sk_live_your_api_key"},
      json=payload,
  )

  form = response.json()
  print("Created form:", form["id"])
  ```
</CodeGroup>

**Example response:**

```json theme={null}
{
  "id": "frm_5pLnK7mQxT",
  "name": "Event Registration",
  "description": "Registration form for the 2025 annual conference.",
  "status": "draft",
  "fields": [
    {
      "id": "fld_a1B2c3D4",
      "label": "Full name",
      "type": "text",
      "required": true,
      "placeholder": "Jane Smith"
    },
    {
      "id": "fld_e5F6g7H8",
      "label": "Email address",
      "type": "email",
      "required": true,
      "placeholder": null
    },
    {
      "id": "fld_i9J0k1L2",
      "label": "Which sessions will you attend?",
      "type": "checkbox",
      "required": false,
      "options": ["Keynote", "Workshop A", "Workshop B", "Networking Lunch"]
    }
  ],
  "submission_count": 0,
  "created_at": "2025-01-15T11:00:00Z",
  "updated_at": "2025-01-15T11:00:00Z"
}
```

***

## Get a form

`GET /forms/{id}`

Returns a single form including all its fields.

### Path parameters

<ParamField path="id" type="string" required>
  The form ID, e.g. `frm_5pLnK7mQxT`.
</ParamField>

### Response

Returns the full form object (same structure as the create response above).

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT" \
    --header "Authorization: Bearer sk_live_your_api_key"
  ```

  ```python Python theme={null}
  import requests

  form_id = "frm_5pLnK7mQxT"

  response = requests.get(
      f"https://api.formflows.ai/v1/forms/{form_id}",
      headers={"Authorization": "Bearer sk_live_your_api_key"},
  )

  form = response.json()
  print(form["name"], "—", len(form["fields"]), "fields")
  ```
</CodeGroup>

***

## Update a form

`PATCH /forms/{id}`

Updates one or more properties of an existing form. Only include the fields you want to change — omitted fields are left unchanged.

### Path parameters

<ParamField path="id" type="string" required>
  The form ID to update.
</ParamField>

### Body parameters

<ParamField body="name" type="string">
  New display name for the form.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

<ParamField body="status" type="string">
  New status. One of `draft`, `published`, or `archived`.
</ParamField>

<ParamField body="fields" type="object[]">
  Replaces the entire fields array. Include existing field IDs to preserve them; omit an ID to create a new field. Fields not included in the array are removed.
</ParamField>

### Response

Returns the updated form object.

<CodeGroup>
  ```bash curl theme={null}
  curl --request PATCH \
    --url "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT" \
    --header "Authorization: Bearer sk_live_your_api_key" \
    --header "Content-Type: application/json" \
    --data '{"status": "published"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT",
      headers={"Authorization": "Bearer sk_live_your_api_key"},
      json={"status": "published"},
  )

  updated_form = response.json()
  print("Status is now:", updated_form["status"])
  ```
</CodeGroup>

***

## Delete a form

`DELETE /forms/{id}`

<Warning>
  Deleting a form is permanent and cannot be undone. All submissions associated with the form are also permanently deleted. Export your data before calling this endpoint.
</Warning>

### Path parameters

<ParamField path="id" type="string" required>
  The form ID to delete.
</ParamField>

### Response

Returns a `204 No Content` response on success, with no body.

<CodeGroup>
  ```bash curl theme={null}
  curl --request DELETE \
    --url "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT" \
    --header "Authorization: Bearer sk_live_your_api_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT",
      headers={"Authorization": "Bearer sk_live_your_api_key"},
  )

  if response.status_code == 204:
      print("Form deleted successfully.")
  ```
</CodeGroup>