Skip to content
Docs menu

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.