Skip to content
Create a Form

Developers

Forms API

Create, read, update, publish and delete forms.

List forms

GET /forms?status=published&q=apply&page=1&limit=50 · scope forms:read

{ "data": [{ "id": "6650…", "slug": "k3x9m2pq7a", "title": "Job application", "status": "published",
             "response_count": 42, "published_version": 3, "has_unpublished_changes": false, … }],
  "total": 1 }

Create a form

POST /forms · scope forms:write

{ "title": "Job application", "template": "job-application" }

Fields (all optional): title, description, template (a template slug) or definition (a full form definition). Without either you get a starter form. Returns 201 with the form.

Get a form

GET /forms/{id} · scope forms:read

Returns the form including draft (the working copy), published (the live version), settings, revision and share_url.

Update a form

PATCH /forms/{id} · scope forms:write

{
  "revision": 7,
  "title": "Senior engineer application",
  "definition": { "schema": { "sections": [ … ] }, "approval": { … } },
  "settings": { "accepting_responses": true, "max_responses": 500, "close_at": "2026-12-31T23:59:00Z" }
}
  • definition replaces the draft completely and is validated; errors come back as 422 with paths like schema.sections[0].elements[2].options.
  • Pass the revision you last read to avoid overwriting someone else’s changes (409 conflict if it changed).
  • Settings: accepting_responses, close_at, max_responses, success_message, redirect_url, show_branding, password* (string to set, null to remove), allow_api_submissions, require_captcha, retention_days*, one_section_per_page, theme ({ "accent_color": "#4f46e5", "rounded": true }). *Pro.

Publish / close

  • POST /forms/{id}/publish — validates the draft and makes it live as a new version.
  • POST /forms/{id}/unpublish — stops accepting responses (status closed).

Duplicate / delete

  • POST /forms/{id}/duplicate — copies the draft and settings into a new draft form.
  • DELETE /forms/{id} — deletes the form and all its responses and files. Returns 204.

Versions

  • GET /forms/{id}/versions — list published versions.
  • GET /forms/{id}/versions/{version} — the definition respondents saw for that version.