# 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](https://staging.formidable.sh/docs/embed/) (`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:

```bash
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

```bash
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:

```json
{
  "entries": [
    {
      "id": 4182,
      "created_at": "2026-11-17T09:12:44+00:00",
      "is_spam": false,
      "is_read": false,
      "spam_reasons": [],
      "data": {"name": "Ann", "email": "ann@example.com", "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

```bash
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": "me@example.com"
  }'
```

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

```bash
# 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

```bash
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

```bash
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](https://staging.formidable.sh/docs/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](https://staging.formidable.sh/docs/api.md) and [https://staging-api.formidable.sh/api/v1/openapi.json](https://staging-api.formidable.sh/api/v1/openapi.json).*
