{"openapi": "3.1.0", "info": {"title": "Formidable API", "version": "v1", "description": "Your forms and their submissions. Docs: https://staging.formidable.sh/docs/api/"}, "servers": [{"url": "https://staging-api.formidable.sh/api/v1"}], "security": [{"token": []}], "components": {"securitySchemes": {"token": {"type": "http", "scheme": "bearer", "description": "API token (fm_...). Scopes: forms:read - List your forms and see their settings, fields and embed links; forms:write - Create, change and pause forms; entries:read - Read submissions and download their files (other people's personal data); entries:write - Mark submissions read or spam, delete them, remove their files"}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}, "paths": {"/me/": {"get": {"summary": "The token you are using", "tags": ["Account"], "parameters": [], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/account/": {"get": {"summary": "You, your plan (and how it is billed), limits, usage and features", "tags": ["Account"], "parameters": [], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:read` scope."}}, "/forms/": {"get": {"summary": "List your forms", "tags": ["Forms"], "parameters": [], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:read` scope."}, "post": {"summary": "Create a form", "tags": ["Forms"], "parameters": [], "responses": {"201": {"description": "Created"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope.", "requestBody": {"required": true, "description": "Properties: name, fields (types: text, email, number, file, textarea, select, checkbox, radio, heading, paragraph), active, enforce_schema, response_type (default|json|redirect), success_redirect_url, email_to (empty = no emails), allowed_websites (list of hosts), captcha (\"formidable\" = our Cloudflare Turnstile check, only on the hosted page / iframe / JS embed; \"none\" = built-in spam protection only - use this for forms posted from your own HTML). New forms get \"formidable\" when it is available.", "content": {"application/json": {"schema": {"type": "object"}, "example": {"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"}}}}}}, "/forms/{form}/": {"get": {"summary": "One form: settings, fields, embed links", "tags": ["Forms"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:read` scope."}, "patch": {"summary": "Change a form (e.g. {\"active\": false} pauses it)", "tags": ["Forms"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope.", "requestBody": {"required": true, "description": "Any of the create properties. Properties: name, fields (types: text, email, number, file, textarea, select, checkbox, radio, heading, paragraph), active, enforce_schema, response_type (default|json|redirect), success_redirect_url, email_to (empty = no emails), allowed_websites (list of hosts), captcha (\"formidable\" = our Cloudflare Turnstile check, only on the hosted page / iframe / JS embed; \"none\" = built-in spam protection only - use this for forms posted from your own HTML). New forms get \"formidable\" when it is available.", "content": {"application/json": {"schema": {"type": "object"}, "example": {"active": false}}}}}, "delete": {"summary": "Delete a form (staff can restore it)", "tags": ["Forms"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"204": {"description": "Done (no content)"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope."}}, "/forms/{form}/entries/": {"get": {"summary": "Submissions, newest first (cursor pagination)", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["submissions", "spam", "all", "deleted"], "default": "submissions"}, "description": "deleted = the trash (restore or purge with the bulk endpoint)"}, {"name": "unread", "in": "query", "schema": {"type": "boolean"}}, {"name": "since", "in": "query", "schema": {"type": "string"}, "description": "ISO date or date-time, inclusive"}, {"name": "until", "in": "query", "schema": {"type": "string"}, "description": "ISO date or date-time, exclusive"}, {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Text search in the answers"}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}, "description": "next_cursor from the previous page"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:read` scope."}}, "/forms/{form}/entries/bulk/": {"post": {"summary": "One action on up to 100 submissions", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:write` scope.", "requestBody": {"required": true, "description": "action: read | unread | spam | not_spam | delete | remove_files, or for submissions in the trash (list them with status=deleted): restore | purge (delete forever, with files)", "content": {"application/json": {"schema": {"type": "object"}, "example": {"action": "spam", "ids": [4182, 4183]}}}}}}, "/forms/{form}/entries/{entry}/": {"get": {"summary": "One submission", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "entry", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:read` scope."}, "patch": {"summary": "Mark read / spam", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "entry", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:write` scope.", "requestBody": {"required": true, "description": "is_read and/or is_spam (booleans)", "content": {"application/json": {"schema": {"type": "object"}, "example": {"is_read": true, "is_spam": false}}}}}, "delete": {"summary": "Delete (moves to the trash)", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "entry", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"204": {"description": "Done (no content)"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:write` scope."}}, "/forms/{form}/entries/{entry}/remove-files/": {"post": {"summary": "Delete the submission's files, keep the submission", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "entry", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:write` scope."}}, "/forms/{form}/design/": {"get": {"summary": "How the form looks: design, colours, corners, font, thank-you text...", "tags": ["Design"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:read` scope."}, "patch": {"summary": "Change the look", "tags": ["Design"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope.", "requestBody": {"required": true, "description": "Any of: template (minimal|card|modern-dark|plain), delivery (page|iframe|embed), color_scheme (light|dark), width (small|medium|large or 240-1200 px), align, title, subtitle, hide_title, hide_subtitle, logo_url, logo_url_dark, brand_color (hex or null), corners (square|small|medium|large|xl or null), font (sans|serif|rounded|mono or null), success_title, success_message, hide_branding (paid plans).", "content": {"application/json": {"schema": {"type": "object"}, "example": {"template": "card", "brand_color": "#16a34a", "corners": "large", "success_title": "Thanks!"}}}}}}, "/forms/{form}/webhooks/": {"get": {"summary": "The form's webhooks with recent deliveries", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:read` scope."}, "post": {"summary": "Add a webhook (paid plans). The response includes its signing secret, shown once.", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}], "responses": {"201": {"description": "Created"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope.", "requestBody": {"required": true, "description": "url (public http/https), include_spam", "content": {"application/json": {"schema": {"type": "object"}, "example": {"url": "https://example.com/hooks/formidable", "include_spam": false}}}}}}, "/forms/{form}/webhooks/{webhook}/": {"get": {"summary": "One webhook with its last 30 deliveries", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "webhook", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:read` scope."}, "patch": {"summary": "Change it: url, enabled, include_spam", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "webhook", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope.", "requestBody": {"required": true, "description": "Any of url, enabled, include_spam", "content": {"application/json": {"schema": {"type": "object"}, "example": {"enabled": false}}}}}, "delete": {"summary": "Delete it", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "webhook", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"204": {"description": "Done (no content)"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope."}}, "/forms/{form}/webhooks/{webhook}/rotate-secret/": {"post": {"summary": "New signing secret (returned once; the old one stops working)", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "webhook", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope."}}, "/forms/{form}/webhooks/{webhook}/test/": {"post": {"summary": "Send a test delivery now", "tags": ["Webhooks"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "webhook", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `forms:write` scope."}}, "/forms/{form}/entries/{entry}/files/{file}/": {"get": {"summary": "Download one file (302 to a short-lived link, or the file itself)", "tags": ["Submissions"], "parameters": [{"name": "form", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The form id (its folder)"}, {"name": "entry", "in": "path", "required": true, "schema": {"type": "integer"}}, {"name": "file", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "The file"}, "302": {"description": "Redirect to a 10-minute download link"}, "404": {"description": "Not found"}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Token lacks the scope, or the plan does not allow it", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Needs the `entries:read` scope."}}}}