Formidable API
Manage your forms and their submissions from scripts, integrations and AI
tools. Everything here is also described by the OpenAPI document at
https://staging-api.formidable.sh/api/v1/openapi.json.
To send submissions to a form you don't need this API or a token - see
Embedding a form (POST https://staging.formidable.sh/f/YOUR_FORM_ID/).
Authentication
Create a token in the portal: Account menu → API tokens. Choose what it can do (scopes), optionally limit it to some forms, and optionally set an expiry. The token is shown once - store it like a password.
Send it on every request:
curl -H "Authorization: Bearer fm_YOUR_TOKEN" https://staging-api.formidable.sh/api/v1/forms/
| Scope | Allows |
|---|---|
forms:read |
List forms and see their settings, fields and embed links; your plan and usage |
entries:read |
Read submissions and download their files |
forms:write |
Create, change, pause and delete forms (paid plans) |
entries:write |
Mark submissions read or spam, delete them, remove their files (paid plans) |
What a token can do is also limited by your plan: the Free plan includes read-only access. A token can never reach billing, account settings or admin. Revoke a token in the portal and it stops working at once.
Endpoints
All under https://staging-api.formidable.sh/api/v1/. JSON in, JSON out.
| Method & path | Scope | Returns |
|---|---|---|
GET /me/ |
any | The token you're using |
GET /account/ |
forms:read |
You, your plan and how it's billed, limits, usage, features |
GET /forms/ |
forms:read |
Your forms |
GET /forms/{form}/ |
forms:read |
One form: fields, settings, embed links |
GET /forms/{form}/entries/ |
entries:read |
Submissions, newest first |
GET /forms/{form}/entries/{id}/ |
entries:read |
One submission |
GET /forms/{form}/entries/{id}/files/{file}/ |
entries:read |
The file (a redirect to a 10-minute link, or the file itself) |
POST /forms/ |
forms:write |
Creates a form (201) |
PATCH /forms/{form}/ |
forms:write |
Changes a form, e.g. {"active": false} pauses it |
DELETE /forms/{form}/ |
forms:write |
Deletes a form (204) |
PATCH /forms/{form}/entries/{id}/ |
entries:write |
{"is_read": true}, {"is_spam": false} |
DELETE /forms/{form}/entries/{id}/ |
entries:write |
Moves a submission to the trash (204) |
POST /forms/{form}/entries/{id}/remove-files/ |
entries:write |
Deletes its files, keeps the submission |
POST /forms/{form}/entries/bulk/ |
entries:write |
One action on up to 100 submissions (incl. restore / purge from the trash) |
GET /forms/{form}/design/ |
forms:read |
How the form looks |
PATCH /forms/{form}/design/ |
forms:write |
Change the look: design, colours, corners, font, thank-you text |
GET /forms/{form}/webhooks/ |
forms:read |
Its webhooks, with recent deliveries |
POST /forms/{form}/webhooks/ |
forms:write |
Add one (paid plans); returns its signing secret once (201) |
GET /forms/{form}/webhooks/{id}/ |
forms:read |
One webhook, last 30 deliveries |
PATCH /forms/{form}/webhooks/{id}/ |
forms:write |
url, enabled, include_spam |
DELETE /forms/{form}/webhooks/{id}/ |
forms:write |
Deletes it (204) |
POST /forms/{form}/webhooks/{id}/rotate-secret/ |
forms:write |
New signing secret (returned once) |
POST /forms/{form}/webhooks/{id}/test/ |
forms:write |
Sends a test delivery now |
{form} is the form's id - the same one in its submit URL and embed code.
Listing submissions
curl -H "Authorization: Bearer fm_YOUR_TOKEN" \
"https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/entries/?since=2026-11-01&limit=50"
Query parameters, all optional:
| Parameter | Meaning |
|---|---|
status |
submissions (default, spam left out), spam, all, or deleted (the trash) |
unread |
true for submissions not yet opened in the portal |
since, until |
ISO date or date-time; since is inclusive, until exclusive |
q |
Text search in the answers |
limit |
1-100, default 25 |
cursor |
The next_cursor from the previous page |
Response:
{
"entries": [
{
"id": 4182,
"created_at": "2026-11-17T09:12:44+00:00",
"is_spam": false,
"is_read": false,
"spam_reasons": [],
"data": {"name": "Ann", "email": "[email protected]", "message": "Hello"},
"files": [
{"id": 77, "field": "cv", "name": "cv.pdf", "size": 48211,
"content_type": "application/pdf",
"url": "https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/entries/4182/files/77/"}
],
"notes": {}
}
],
"next_cursor": "4131"
}
Keep calling with cursor=<next_cursor> until it's null. To pick up only
new submissions, remember the newest created_at you've seen and pass it as
since next time.
You see exactly what the portal shows: submissions held because the account
went over its monthly limit, and ones older than the plan's history window,
are left out until the account upgrades. Downloading a file follows the
url with the same Authorization header (curl -L follows the redirect).
Creating and changing forms
curl -X POST https://staging-api.formidable.sh/api/v1/forms/ \
-H "Authorization: Bearer fm_YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Contact us",
"fields": [
{"name": "name", "label": "Your name", "type": "text", "required": true},
{"name": "email", "label": "Email", "type": "email", "required": true},
{"name": "topic", "label": "Topic", "type": "select", "options": ["Sales", "Support"]},
{"name": "message", "label": "Message", "type": "textarea"}
],
"email_to": "[email protected]"
}'
The response is the new form, including its links (hosted page, embed
script, submit URL) - it's live straight away with the default design.
Building your own HTML for it? Send "captcha": "none" too, and add a hidden,
empty input named after the form's honeypot_field.
Properties (all optional when changing a form with PATCH):
| Property | Notes |
|---|---|
name |
Required when creating |
fields |
List of fields. type: text, email, number, file, textarea, select, checkbox, radio (input), heading, paragraph (display only, use content). name: letters, numbers, _, -; unique. options for select/checkbox/radio: strings or {"value", "label"} |
active |
false pauses the form (it rejects submissions), true resumes |
enforce_schema |
true (default) accepts only the listed fields |
response_type |
default (thank-you page), json, or redirect (with success_redirect_url) |
email_to |
Where notification emails go; empty string stops them |
allowed_websites |
List of hosts ("example.com", "*.example.com"); empty list = anywhere |
captcha |
"formidable": our Cloudflare Turnstile check (new forms get it when available). It only works on the hosted page, iframe and JS embed, so for a form posted from your own HTML use "none" (built-in spam protection only). Reads may also show "own" (an own key, set in the portal). |
Creating a form counts against your plan's form limit (403 plan_form_limit
when full). A token limited to particular forms can't create new ones.
Changing submissions
# mark one as not spam (this also teaches the spam checks)
curl -X PATCH https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/entries/4182/ \
-H "Authorization: Bearer fm_YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"is_spam": false}'
# delete several at once (they go to the trash)
curl -X POST https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/entries/bulk/ \
-H "Authorization: Bearer fm_YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"action": "delete", "ids": [4182, 4183]}'
Bulk action: read, unread, spam, not_spam, delete, remove_files,
and for submissions in the trash (status=deleted): restore, or purge
(deletes them and their files for good).
Ids that aren't on this form (or that you can't see) are skipped; the
response says how many were affected. Deleted submissions go to the trash
and are removed for good after the trash period.
Design
curl -X PATCH https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/design/ \
-H "Authorization: Bearer fm_YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"template": "card", "brand_color": "#16a34a", "corners": "large", "font": "rounded",
"success_title": "Thanks!", "success_message": "We reply within a day."}'
Settings: template (minimal, card, modern-dark, plain), delivery
(page, iframe, embed), color_scheme (light, dark), width
(small, medium, large, or 240-1200 pixels), align, title,
subtitle, hide_title, hide_subtitle, logo_url, logo_url_dark,
brand_color (hex, null = the design's own), corners (square,
small, medium, large, xl, null), font (sans, serif,
rounded, mono, null), success_title, success_message,
hide_branding (applies on paid plans). GET lists the choices too.
Webhooks
curl -X POST https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/webhooks/ \
-H "Authorization: Bearer fm_YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/formidable"}'
The response includes secret - the signing secret, shown only now and
after rotate-secret. What gets sent and how to check signatures:
Webhooks. Webhooks are on paid plans
(403 plan_no_webhooks otherwise).
Errors and limits
Errors are {"error": {"code": "...", "message": "..."}}:
| Status | Code | When |
|---|---|---|
400 |
bad_request |
A parameter is invalid (the message says which) |
401 |
unauthorized |
No token, or it's invalid, revoked or expired |
403 |
missing_scope / plan_read_only / plan_no_api / plan_form_limit / plan_no_webhooks / token_limited |
The token or the plan doesn't allow this |
405 |
method_not_allowed |
That method isn't supported on this path |
404 |
not_found |
No such form/submission/file, or the token can't use that form |
429 |
rate_limited |
More than 120 requests a minute with one token |
Machine-readable: https://staging.formidable.sh/docs/api.md and https://staging-api.formidable.sh/api/v1/openapi.json.