Forms

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

integer

default:"20"

Number of forms to return. Maximum 100.

string

Pagination cursor from the previous response’s next_cursor. Omit to start from the beginning.

string

Filter by form status. One of draft, published, or archived.

Response

object[]

Array of form objects.

Show Form object properties

string

Unique form identifier, prefixed with frm_.

string

Display name of the form.

string

Optional description of the form’s purpose.

string

Current status: draft, published, or archived.

integer

Total number of submissions received.

string

ISO 8601 timestamp of when the form was created.

string

ISO 8601 timestamp of the most recent update.

string

Pass this value as the cursor parameter to fetch the next page. null if there are no more results.

boolean

true if additional pages exist.

curl --request GET \
  --url "https://api.formflows.ai/v1/forms?limit=10&status=published" \
  --header "Authorization: Bearer sk_live_your_api_key"

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"])

Example response:

{
  "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

string

required

Display name for the form. Maximum 200 characters.

string

Optional description of the form’s purpose.

object[]

Array of field definitions to include in the form.

Show Field object properties

string

required

The field label shown to respondents.

string

required

Field type. One of text, email, number, dropdown, checkbox, radio, textarea, file, date.

boolean

default:"false"

Whether the field must be filled before the form can be submitted.

string[]

For dropdown, checkbox, and radio fields — the list of selectable options.

string

Placeholder text shown inside the input.

Response

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

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"]
      }
    ]
  }'

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"])

Example response:

{
  "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

string

required

The form ID, e.g. frm_5pLnK7mQxT.

Response

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

curl --request GET \
  --url "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT" \
  --header "Authorization: Bearer sk_live_your_api_key"

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")

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

string

required

The form ID to update.

Body parameters

string

New display name for the form.

string

Updated description.

string

New status. One of draft, published, or archived.

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.

Response

Returns the updated form object.

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"}'

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"])

Delete a form

DELETE /forms/{id}

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.

Path parameters

string

required

The form ID to delete.

Response

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

curl --request DELETE \
  --url "https://api.formflows.ai/v1/forms/frm_5pLnK7mQxT" \
  --header "Authorization: Bearer sk_live_your_api_key"

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.")

Overview

Endpoints

List forms

Query parameters

Response

Create a form

Body parameters

Response

Get a form

Path parameters

Response

Update a form

Path parameters

Body parameters

Response

Delete a form

Path parameters

Response

​List forms

​Query parameters

​Response

​Create a form

​Body parameters

​Response

​Get a form

​Path parameters

​Response

​Update a form

​Path parameters

​Body parameters

​Response

​Delete a form

​Path parameters

​Response

List forms

Query parameters

Response

Create a form

Body parameters

Response

Get a form

Path parameters

Response

Update a form

Path parameters

Body parameters

Response

Delete a form

Path parameters

Response