Private beta Request access

Forms

Create, update, publish and organise forms.

List forms

GET /api/v1/forms

Returns the forms in the active workspace that the caller can access, most recently updated first. Trashed forms are excluded unless status=trashed is requested. Service accounts see every form in the instance.

Service account scope: forms:read

query parameters

limit integer default 25
Maximum number of items to return.
offset integer default 0
Number of items to skip.
status string
Only return forms with this status. One of active, archived, disabled, trashed
q string
Only return forms whose title contains this text.

Example request

curl "https://acme.formcel.com/api/v1/forms" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 200 A page of forms.
  • 401 The API key is missing or invalid.

Response body FormList

data array of FormSummary required
total integer required
limit integer required
offset integer required

FormSummary

id string required
title string required
status string required
active, archived, disabled or trashed. New values may be added.
current_version integer required
Latest published version; 0 if never published.
created_at string (date-time) required
updated_at string (date-time) required

Create a form

POST /api/v1/forms

Creates a blank draft form in the active workspace. The caller becomes its owner. Requires edit access to the workspace.

Service account scope: forms:write

Request body

title string
Defaults to "Untitled Form" when empty.
folder_id string
Folder to create the form in.

Example request

curl -X POST "https://acme.formcel.com/api/v1/forms" \
  -H "Authorization: Bearer $FORMCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Customer feedback"}'

Responses

  • 201 The created form.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.

Response body FormDetail

id string required
title string required
slug string
Custom URL slug. Omitted when not set.
status string required
active, archived, disabled or trashed. New values may be added.
favorite boolean required
current_version integer required
Latest published version; 0 if never published.
publish_mode string required
draft (changes go live on publish) or auto (changes publish automatically).
folder_id string
Omitted when the form is unfiled.
opens_at string (date-time)
Submissions open at this time.
closes_at string (date-time)
Submissions close at this time.
max_submissions integer
Submission limit.
closed_message string
Shown to respondents when the form is closed.
timezone string
IANA time zone used for opens_at and closes_at.
created_at string (date-time) required
updated_at string (date-time) required
role string required
The caller's role on the form: owner, editor or viewer. Treat unknown values as no access.

Get a form

GET /api/v1/forms/{id}

Service account scope: forms:read

path parameters

id string required
Form ID.

Example request

curl "https://acme.formcel.com/api/v1/forms/ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 200 The form, including the caller's role on it.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body FormDetail

id string required
title string required
slug string
Custom URL slug. Omitted when not set.
status string required
active, archived, disabled or trashed. New values may be added.
favorite boolean required
current_version integer required
Latest published version; 0 if never published.
publish_mode string required
draft (changes go live on publish) or auto (changes publish automatically).
folder_id string
Omitted when the form is unfiled.
opens_at string (date-time)
Submissions open at this time.
closes_at string (date-time)
Submissions close at this time.
max_submissions integer
Submission limit.
closed_message string
Shown to respondents when the form is closed.
timezone string
IANA time zone used for opens_at and closes_at.
created_at string (date-time) required
updated_at string (date-time) required
role string required
The caller's role on the form: owner, editor or viewer. Treat unknown values as no access.

Update a form

PATCH /api/v1/forms/{id}

Updates form settings. Only the fields present in the body change. Fields that accept null are cleared when sent as null. Requires the owner or editor role.

Service account scope: forms:write

path parameters

id string required
Form ID.

Request body

title string
slug string or null
Custom URL slug; must be unique.
status string
One of active, archived, disabled
favorite boolean
publish_mode string
One of draft, auto
folder_id string or null
Send null to unfile the form.
opens_at string or null (date-time)
closes_at string or null (date-time)
max_submissions integer or null
closed_message string or null
timezone string or null

Example request

curl -X PATCH "https://acme.formcel.com/api/v1/forms/ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Customer feedback 2026","closes_at":"2026-12-31T23:59:59Z"}'

Responses

  • 200 The updated form.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body FormDetail

id string required
title string required
slug string
Custom URL slug. Omitted when not set.
status string required
active, archived, disabled or trashed. New values may be added.
favorite boolean required
current_version integer required
Latest published version; 0 if never published.
publish_mode string required
draft (changes go live on publish) or auto (changes publish automatically).
folder_id string
Omitted when the form is unfiled.
opens_at string (date-time)
Submissions open at this time.
closes_at string (date-time)
Submissions close at this time.
max_submissions integer
Submission limit.
closed_message string
Shown to respondents when the form is closed.
timezone string
IANA time zone used for opens_at and closes_at.
created_at string (date-time) required
updated_at string (date-time) required
role string required
The caller's role on the form: owner, editor or viewer. Treat unknown values as no access.

Delete a form

DELETE /api/v1/forms/{id}

Moves the form to the trash. Only the owner can delete a form.

Service account scope: forms:write

path parameters

id string required
Form ID.

Example request

curl -X DELETE "https://acme.formcel.com/api/v1/forms/ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 204 The form was moved to the trash.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

List form fields

GET /api/v1/forms/{id}/fields

Returns the fields of the published form in a simplified shape for mapping submission data in integrations. Not paginated.

Service account scope: forms:read

path parameters

id string required
Form ID.

Example request

curl "https://acme.formcel.com/api/v1/forms/ID/fields" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 200 The form's fields.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body FormFields

form_id string required
fields array of FormField required

FormField

key string required
Key of the field's value in submission data.
label string required
type string required
string, number, boolean or file. New values may be added.
required boolean required

Duplicate a form

POST /api/v1/forms/{id}/duplicate

Creates a copy of the form. Any role can duplicate; the caller owns the copy.

Service account scope: forms:write

path parameters

id string required
Form ID.

Example request

curl -X POST "https://acme.formcel.com/api/v1/forms/ID/duplicate" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 201 The new form.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body FormDetail

id string required
title string required
slug string
Custom URL slug. Omitted when not set.
status string required
active, archived, disabled or trashed. New values may be added.
favorite boolean required
current_version integer required
Latest published version; 0 if never published.
publish_mode string required
draft (changes go live on publish) or auto (changes publish automatically).
folder_id string
Omitted when the form is unfiled.
opens_at string (date-time)
Submissions open at this time.
closes_at string (date-time)
Submissions close at this time.
max_submissions integer
Submission limit.
closed_message string
Shown to respondents when the form is closed.
timezone string
IANA time zone used for opens_at and closes_at.
created_at string (date-time) required
updated_at string (date-time) required
role string required
The caller's role on the form: owner, editor or viewer. Treat unknown values as no access.

Publish a form

POST /api/v1/forms/{id}/publish

Publishes the current draft as a new immutable version. Warnings are informational; a response with warnings is still a successful publish. Requires the owner or editor role.

Service account scope: forms:write

path parameters

id string required
Form ID.

Example request

curl -X POST "https://acme.formcel.com/api/v1/forms/ID/publish" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 200 The published version.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body PublishResponse

version integer required
published_at string (date-time) required
warnings array of string required