{ "openapi": "3.1.0", "info": { "title": "formformform Forms API", "version": "1.0.0", "description": "Public form management API: forms, fields, templates and submissions. Create a key in Settings → API Keys. Supply Authorization: Bearer and Accept: application/json. Read and write keys permit mutations; read-only keys permit reads and exports. Keys cannot manage your account, password or billing. This reference covers the form-building API, not the separate mobile account, store billing or OAuth connector APIs." }, "servers": [ { "url": "https://app.formformform.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/auth/login": { "post": { "operationId": "login", "summary": "Sign in for a token", "description": "Optional alternative to creating a key in Settings. Login tokens have broad account access, unlike scoped API keys. Wrong credentials return 422. After five failed passwords per email and IP, requests are throttled for up to a minute. A two-factor account returns a challenge instead of a token.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TokenResponse" }, { "$ref": "#/components/schemas/ChallengeResponse" } ] } } } }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" }, "example": { "email": "you@example.com", "password": "YOUR_PASSWORD", "device_name": "my-integration" } } } } } }, "/auth/two-factor-challenge": { "post": { "operationId": "completeTwoFactor", "summary": "Complete two-factor sign-in", "description": "The challenge expires after five minutes and is consumed on every attempt, including failed attempts. Sign in again for a fresh challenge before retrying. Pass device_name here too if you want a custom label.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwoFactorChallenge" }, "example": { "challenge_token": "CHALLENGE_FROM_LOGIN", "code": "123456", "device_name": "my-integration" } } } } } }, "/auth/me": { "get": { "operationId": "getCurrentUser", "summary": "Check your authentication", "description": " Available to read-only and read and write API keys.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/auth/logout": { "post": { "operationId": "revokeCurrentToken", "summary": "Revoke the current token", "description": "Immediately revokes only the key or token used for this request. Available to read-only and read and write API keys.", "tags": [ "Authentication" ], "responses": { "204": { "description": "Successful response." }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/forms": { "get": { "operationId": "listForms", "summary": "List your forms", "description": "Newest first. Includes field counts and plan metadata; use GET /forms/{form} for field definitions. Pagination defaults to 25, capped at 100. Available to read-only and read and write API keys.", "tags": [ "Forms" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at 1." }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] }, "post": { "operationId": "createForm", "summary": "Create a form", "description": "Send settings and an optional template slug. The blank template seeds a heading, one short_text field and a submit_button. Custom fields arrays are ignored here. Use is_active: false while assembling the form. Requires a read and write API key.", "tags": [ "Forms" ], "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormCreate" }, "example": { "title": "Contact us", "template": "blank", "is_active": false, "thank_you_message": "Thanks — we will be in touch." } } } } } }, "/forms/{form}": { "get": { "operationId": "getForm", "summary": "Read a form and its fields", "description": " Available to read-only and read and write API keys.", "tags": [ "Forms" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ] }, "patch": { "operationId": "updateForm", "summary": "Update form settings", "description": "Updates only supplied settings. Renaming the form changes its slug but does not change the heading field label; edit that field separately. Set is_active explicitly for repeatable activation. Requires a read and write API key.", "tags": [ "Forms" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpdate" }, "example": { "title": "Contact our team", "is_active": true } } } } }, "delete": { "operationId": "deleteForm", "summary": "Delete a form", "description": "Permanently deletes the form, its responses and associated stored files. There is no confirmation parameter on v1. Requires a read and write API key.", "tags": [ "Forms" ], "responses": { "204": { "description": "Successful response." }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ] } }, "/forms/{form}/duplicate": { "post": { "operationId": "duplicateForm", "summary": "Duplicate a form", "description": "Copies fields and supported settings, including active status and encryption configuration; does not copy submissions. Requires a title. Requires a read and write API key.", "tags": [ "Forms" ], "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateForm" }, "example": { "title": "Contact us — copy" } } } } } }, "/forms/{form}/toggle-active": { "patch": { "operationId": "toggleFormActive", "summary": "Toggle whether a form accepts responses", "description": "Flips the current value. Prefer PATCH /forms/{form} with an explicit is_active value in retryable automation. Requires a read and write API key.", "tags": [ "Forms" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ] } }, "/templates": { "get": { "operationId": "listTemplates", "summary": "List available form templates", "description": "Returns categories in data, each containing a templates array. Use a template’s id (its slug) in POST /forms. Available to read-only and read and write API keys.", "tags": [ "Forms" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/forms/{form}/fields": { "post": { "operationId": "createField", "summary": "Add a field", "description": "Creates one field. position inserts at a zero-based index, shifting later fields. Omit it to append; insert before the existing submit button for a normal question. Requires a read and write API key.", "tags": [ "Fields" ], "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldCreate" }, "example": { "type": "email", "label": "Email address", "is_required": true, "position": 2 } } } } } }, "/forms/{form}/fields/{field}": { "patch": { "operationId": "updateField", "summary": "Edit a field", "description": "Uses the numeric field id from the owner API. Updates supplied properties. Read the existing field first and preserve the parts of settings and logic you want to keep. Requires a read and write API key.", "tags": [ "Fields" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." }, { "name": "field", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Numeric field ID from the owner API." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldUpdate" }, "example": { "label": "Your email", "is_required": true, "placeholder": "you@example.com" } } } } }, "delete": { "operationId": "deleteField", "summary": "Delete a field", "description": "Permanently deletes a field and its associated stored files. The endpoint does not preserve the heading or submit button for you; keep both when editing. Requires a read and write API key.", "tags": [ "Fields" ], "responses": { "204": { "description": "Successful response." }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." }, { "name": "field", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Numeric field ID from the owner API." } ] } }, "/forms/{form}/fields/reorder": { "post": { "operationId": "reorderFields", "summary": "Reorder fields", "description": "Use numeric IDs from a fresh GET of the form. Send every field once, with the heading first and submit button last. IDs are not UUIDs. Requires a read and write API key.", "tags": [ "Fields" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reorder" }, "example": { "ids": [ 101, 102, 104, 103 ] } } } } } }, "/forms/{form}/submissions": { "get": { "operationId": "listSubmissions", "summary": "List responses", "description": "Newest first; paginated, with today_count alongside data. Match values by field_uuid. Encrypted payload is only available on the detail endpoint. Available to read-only and read and write API keys.", "tags": [ "Submissions" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionList" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at 1." }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ] } }, "/forms/{form}/submissions/export": { "get": { "operationId": "exportSubmissions", "summary": "Export responses as CSV", "description": "Returns CSV bytes, not a JSON envelope. Columns are input fields, Submitted At, IP Address, Filled At and Was Offline. Encrypted answers cannot be decrypted by the server. Available to read-only and read and write API keys.", "tags": [ "Submissions" ], "responses": { "200": { "description": "Successful response.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." } ] } }, "/forms/{form}/submissions/{submission}": { "get": { "operationId": "getSubmission", "summary": "Read one response", "description": "Submission is a UUID. Includes encrypted_payload on encrypted forms, and prev/next UUIDs when neighbours exist. Available to read-only and read and write API keys.", "tags": [ "Submissions" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." }, { "name": "submission", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Submission UUID." } ] }, "delete": { "operationId": "deleteSubmission", "summary": "Delete a response", "description": "Permanently removes the response. Requires a read and write API key.", "tags": [ "Submissions" ], "responses": { "204": { "description": "Successful response." }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "form", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Form UUID from the owner API." }, { "name": "submission", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Submission UUID." } ] } }, "/public/forms/{public_id}": { "get": { "operationId": "getPublicForm", "summary": "Read an active form without authentication", "description": "Public field id values are UUID strings. This request increments the form view count. Inactive forms return 404.", "tags": [ "Public forms" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormResponse" } } } }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Short public share identifier." } ] } }, "/public/forms/{public_id}/submissions": { "post": { "operationId": "submitPublicForm", "summary": "Submit answers without authentication", "description": "Uses field UUIDs as fields keys. Uploaded files named by upload_uuids are attached on both public submission APIs. Paid forms require online checkout and return 409 here.", "tags": [ "Public forms" ], "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionReceipt" } } } }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "description": "Paid forms require online checkout." }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Short public share identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSubmission" }, "example": { "fields": { "11111111-1111-4111-8111-111111111111": "you@example.com" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from /settings/api-keys or a login-issued Sanctum token." } }, "schemas": { "ValidationError": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] }, "FormCreate": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "thank_you_message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "redirect_url": { "anyOf": [ { "type": "string", "description": "HTTP or HTTPS URL.", "format": "uri", "maxLength": 500 }, { "type": "null" } ] }, "notify_on_submission": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Defaults to true." }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Defaults to true. Send false while building." }, "template": { "type": "string", "description": "Template slug returned as templates[].id by GET /templates. Default blank; an unknown slug falls back to blank.", "maxLength": 100 } }, "required": [ "title" ], "description": "Create a form seeded from a template. fields is not accepted here; add or edit fields through the field endpoints. Use is_active: false while building." }, "FormUpdate": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "thank_you_message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "redirect_url": { "anyOf": [ { "type": "string", "description": "HTTP or HTTPS URL.", "format": "uri", "maxLength": 500 }, { "type": "null" } ] }, "notify_on_submission": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "show_branded_footer": { "type": "boolean", "description": "Only paid accounts can remove branding; free accounts are forced to true." }, "is_encrypted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "encryption_public_key": { "anyOf": [ { "type": "string", "description": "Armoured PGP PUBLIC KEY BLOCK; required when enabling encryption unless one is already stored.", "maxLength": 20000 }, { "type": "null" } ] }, "encryption_key_fingerprint": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "description": "Partial settings update. fields, slug and public_id are ignored. Encryption configuration freezes after the first submission; locked encryption changes are ignored. Payment forms cannot enable encryption." }, "FieldSettings": { "anyOf": [ { "type": "object", "properties": { "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "step": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "max_length": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "rows": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 50 }, { "type": "null" } ] }, "min_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "max_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "field_width": { "anyOf": [ { "type": "string", "enum": [ "small", "medium", "large", "full" ] }, { "type": "null" } ] }, "button_alignment": { "anyOf": [ { "type": "string", "enum": [ "left", "center", "right" ] }, { "type": "null" } ] }, "accept": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "max_size": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 51200, "description": "Field metadata in KB. Actual uploads have a separate server-enforced 2 MB limit." }, { "type": "null" } ] }, "alt": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "image_uuid": { "anyOf": [ { "type": "string", "maxLength": 36 }, { "type": "null" } ] } } }, { "type": "null" } ] }, "FieldLogic": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "show", "require" ] }, "condition_type": { "type": "string", "enum": [ "all", "any" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field_uuid": { "type": "string", "format": "uuid", "description": "UUID of another field on this form, not its numeric id." }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "greater_than", "less_than", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "field_uuid", "operator" ] } } }, "description": "Send null to remove logic. Configure after creating the referenced fields." }, { "type": "null" } ] }, "FieldCreate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "number", "phone", "date", "dropdown", "radio", "checkbox", "file", "heading", "paragraph", "divider", "image", "hidden", "page_break", "payment", "submit_button" ] }, "label": { "anyOf": [ { "type": "string", "description": "Required on creation except paragraph, divider, image and page_break.", "maxLength": 255 }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string", "description": "Paragraph HTML or image URL, according to type.", "maxLength": 10000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 255 } }, { "type": "null" } ] }, "default_value": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "settings": { "$ref": "#/components/schemas/FieldSettings" }, "logic": { "$ref": "#/components/schemas/FieldLogic" }, "is_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Zero-based insertion position; omitted or null appends." }, { "type": "null" } ] } }, "required": [ "type" ], "description": "One field per request. label is required except for paragraph, divider, image and page_break. options is required for dropdown, radio and checkbox. payment is a supported type but checkout configuration requires the editor.", "allOf": [ { "if": { "properties": { "type": { "not": { "enum": [ "paragraph", "divider", "image", "page_break" ] } } } }, "then": { "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255 } } } }, { "if": { "properties": { "type": { "enum": [ "dropdown", "radio", "checkbox" ] } } }, "then": { "required": [ "options" ], "properties": { "options": { "type": "array", "minItems": 1, "items": { "type": "string", "maxLength": 255 } } } } } ] }, "FieldUpdate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "number", "phone", "date", "dropdown", "radio", "checkbox", "file", "heading", "paragraph", "divider", "image", "hidden", "page_break", "payment", "submit_button" ] }, "label": { "anyOf": [ { "type": "string", "description": "Required on creation except paragraph, divider, image and page_break.", "maxLength": 255 }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string", "description": "Paragraph HTML or image URL, according to type.", "maxLength": 10000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 255 } }, { "type": "null" } ] }, "default_value": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "settings": { "$ref": "#/components/schemas/FieldSettings" }, "logic": { "$ref": "#/components/schemas/FieldLogic" }, "is_required": { "type": "boolean" } }, "description": "Partial field update. position and uuid are ignored; use reorder to move fields. When changing type, include a compatible label and options. settings and logic replace their stored objects; send the whole desired object." }, "Field": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "number", "phone", "date", "dropdown", "radio", "checkbox", "file", "heading", "paragraph", "divider", "image", "hidden", "page_break", "payment", "submit_button" ] }, "label": { "anyOf": [ { "type": "string", "description": "Required on creation except paragraph, divider, image and page_break.", "maxLength": 255 }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string", "description": "Paragraph HTML or image URL, according to type.", "maxLength": 10000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 255 } }, { "type": "null" } ] }, "default_value": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "settings": { "$ref": "#/components/schemas/FieldSettings" }, "logic": { "$ref": "#/components/schemas/FieldLogic" }, "is_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "form_id": { "type": "integer" }, "position": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "uuid", "type", "position" ] }, "Form": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "thank_you_message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "redirect_url": { "anyOf": [ { "type": "string", "description": "HTTP or HTTPS URL.", "format": "uri", "maxLength": 500 }, { "type": "null" } ] }, "notify_on_submission": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "show_branded_footer": { "type": "boolean", "description": "Only paid accounts can remove branding; free accounts are forced to true." }, "is_encrypted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "encryption_public_key": { "anyOf": [ { "type": "string", "description": "Armoured PGP PUBLIC KEY BLOCK; required when enabling encryption unless one is already stored.", "maxLength": 20000 }, { "type": "null" } ] }, "encryption_key_fingerprint": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "public_id": { "type": "string", "description": "Short stable share identifier." }, "user_id": { "type": "integer" }, "slug": { "type": "string", "description": "Derived from title; may change when renamed." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "fields_count": { "type": "integer" }, "views_count": { "type": "integer" }, "submissions_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "public_id", "slug", "title", "is_active" ], "description": "fields is included on create, show, update, duplicate and toggle responses, not the paginated list. fields_count is included on the list." }, "FormResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Form" } }, "required": [ "data" ] }, "FieldResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Field" } }, "required": [ "data" ] }, "PaginationMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "from": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "path": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "type": "string" }, "active": { "type": "boolean" } } } }, "form_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "plan_name": { "type": "string" } } }, "PaginationLinks": { "type": "object", "properties": { "first": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prev": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "FormList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "links", "meta" ] }, "SubmissionValue": { "type": "object", "properties": { "form_field_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "field_uuid": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "field_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "field_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "description": "Text, number or selected values depending on the field. Checkbox values are arrays. File values identify uploads." } } }, "Submission": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "was_offline": { "type": "boolean" }, "payment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "order": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "currency": { "type": "string" }, "total_minor": { "type": "integer" }, "tax_minor": { "type": "integer" } } }, { "type": "null" } ] }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/SubmissionValue" } }, "encrypted_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prev": { "type": "string", "format": "uuid" }, "next": { "type": "string", "format": "uuid" } }, "required": [ "uuid" ], "description": "encrypted_payload appears only on detail. prev and next are omitted at the ends of the list. Empty or hidden answers can be absent from values; match by field_uuid." }, "SubmissionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Submission" } }, "required": [ "data" ] }, "SubmissionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Submission" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "today_count": { "type": "integer" } }, "required": [ "data" ] }, "TemplateList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Template slug used by POST /forms." }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "number", "phone", "date", "dropdown", "radio", "checkbox", "file", "heading", "paragraph", "divider", "image", "hidden", "page_break", "payment", "submit_button" ] }, "label": { "anyOf": [ { "type": "string", "description": "Required on creation except paragraph, divider, image and page_break.", "maxLength": 255 }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string", "description": "Paragraph HTML or image URL, according to type.", "maxLength": 10000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 255 } }, { "type": "null" } ] }, "default_value": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "settings": { "$ref": "#/components/schemas/FieldSettings" }, "logic": { "$ref": "#/components/schemas/FieldLogic" }, "is_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } } } } } } } } } }, "required": [ "data" ] }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "two_factor_enabled": { "type": "boolean" }, "has_password": { "type": "boolean" }, "store_app_account_id": { "type": "string", "format": "uuid" }, "plan": { "type": "object", "properties": { "name": { "type": "string" }, "form_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } } }, "UserResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] }, "Login": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "device_name": { "type": "string", "description": "Token label; defaults to mobile." } }, "required": [ "email", "password" ] }, "TokenResponse": { "type": "object", "properties": { "token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "two_factor": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "token", "token_type", "user" ] }, "ChallengeResponse": { "type": "object", "properties": { "two_factor": { "const": true }, "challenge_token": { "type": "string" } }, "required": [ "two_factor", "challenge_token" ] }, "TwoFactorChallenge": { "type": "object", "properties": { "challenge_token": { "type": "string" }, "code": { "type": "string", "description": "Six-digit authenticator code." }, "recovery_code": { "type": "string", "description": "Alternative to code; consumed after use." }, "device_name": { "type": "string" } }, "required": [ "challenge_token" ], "anyOf": [ { "required": [ "code" ] }, { "required": [ "recovery_code" ] } ] }, "Reorder": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "ids" ], "description": "Send all numeric field IDs from this form once, in the desired order. This endpoint does not require a complete list; a partial list can leave ambiguous positions." }, "PublicField": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "number", "phone", "date", "dropdown", "radio", "checkbox", "file", "heading", "paragraph", "divider", "image", "hidden", "page_break", "payment", "submit_button" ] }, "label": { "anyOf": [ { "type": "string", "description": "Required on creation except paragraph, divider, image and page_break.", "maxLength": 255 }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string", "description": "Paragraph HTML or image URL, according to type.", "maxLength": 10000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 255 } }, { "type": "null" } ] }, "default_value": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "settings": { "$ref": "#/components/schemas/FieldSettings" }, "logic": { "$ref": "#/components/schemas/FieldLogic" }, "is_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "description": "Public id is a UUID string, unlike owner API field ids." }, "uuid": { "type": "string", "format": "uuid" }, "position": { "type": "integer" } } }, "PublicFormResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "title": { "type": "string" }, "public_id": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thank_you_message": { "type": "string" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PublicField" } } } } }, "required": [ "data" ] }, "PublicSubmission": { "type": "object", "properties": { "fields": { "type": "object", "additionalProperties": {}, "description": "Answers keyed by the field UUID returned by the public form. Checkbox answers are arrays of option strings." }, "encrypted_payload": { "type": "string", "description": "Armoured PGP message for encrypted forms; omit fields." }, "upload_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 }, "client_uuid": { "type": "string", "format": "uuid" }, "filled_at": { "type": "string", "format": "date-time" }, "was_offline": { "type": "boolean" } }, "description": "For ordinary forms use fields. Encrypted forms require encrypted_payload and prohibit fields. Payment forms return 409 on this endpoint. client_uuid enables deduplication of offline retries." }, "SubmissionReceipt": { "type": "object", "properties": { "message": { "type": "string" }, "submission_uuid": { "type": "string", "format": "uuid" }, "thank_you_message": { "type": "string" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "submission_uuid" ] }, "DuplicateForm": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "title" ] }, "Success": { "type": "object", "properties": { "success": { "type": "boolean" } } } }, "responses": { "Error403": { "description": "Access denied: key permissions, ownership, or account restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Error404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Error422": { "description": "Validation failed. Inspect errors before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Error429": { "description": "Too many requests. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Error401": { "description": "Missing, invalid or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } }, "externalDocs": { "url": "https://www.formformform.com/api" } }