Forms - SE&M

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

limit

integer

default:"20"

Number of forms to return. Maximum 100.

cursor

string

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

status

string

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

Response

data

object[]

Array of form objects.

Show Form object properties

string

Unique form identifier, prefixed with frm_.

name

string

Display name of the form.

description

string

Optional description of the form’s purpose.

status

string

Current status: draft, published, or archived.

submission_count

integer

Total number of submissions received.

created_at

string

ISO 8601 timestamp of when the form was created.

updated_at

string

ISO 8601 timestamp of the most recent update.

next_cursor

string

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

has_more

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

name

string

required

Display name for the form. Maximum 200 characters.

description

string

Optional description of the form’s purpose.

fields

object[]

Array of field definitions to include in the form.

Show Field object properties

label

string

required

The field label shown to respondents.

type

string

required

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

required

boolean

default:"false"

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

options

string[]

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

placeholder

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

name

string

New display name for the form.

description

string

Updated description.

status

string

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

fields

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

​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