Developers

Public forms & headless use

Render forms in your own UI and submit them without an API key.

Public endpoints need no authentication and can be called from any website (CORS allows all origins). They are what the hosted form pages use, so you can build fully custom UIs on top of the same validation engine.

Fetch a form

GET /public/forms/{slug}

{
  "slug": "k3x9m2pq7a",
  "title": "Contact us",
  "version": 3,
  "schema": { "sections": [ … ] },
  "accepting_responses": true,
  "closed_reason": null,
  "captcha_required": false,
  "password_required": false,
  "approval": { "enabled": true, "show_result": true }
}

Approval criteria (expected answers) are never included.

Password-protected forms

If password_required is true, exchange the password for an access token and send it as X-Form-Access on the other public calls:

curl -X POST https://your-domain/api/v1/public/forms/$SLUG/unlock \
  -H "Content-Type: application/json" -d '{ "password": "…" }'
# → { "access_token": "…", "expires_in": 43200 }

Upload a file

POST /public/forms/{slug}/uploads — multipart/form-data with the fields item_id first, then file.

curl -X POST https://your-domain/api/v1/public/forms/$SLUG/uploads \
  -F item_id=cv -F file=@resume.pdf
# → { "ref": "6650…e1.Xy7…", "name": "resume.pdf", "size": 48211, "type": "application/pdf", "expires_in": 86400 }

Use the returned ref as the answer of the file question: "cv": ["6650…e1.Xy7…"]. A reference can be used once and expires after 24 hours.

Submit

POST /public/forms/{slug}/submissions

{
  "answers": { "full_name": "Ada", "email": "ada@example.com", "cv": ["6650…e1.Xy7…"] },
  "captcha_token": null,
  "duration_ms": 52000
}

Response 201:

{
  "id": "6650c1f2a9e4b3d2c1f0a9b8",
  "message": "Thanks! Your response has been recorded.",
  "redirect_url": null,
  "result": { "status": "approved", "message": "Welcome aboard!", "score": 2, "max_score": 2, "percent": 100 }
}

result is only present when the form shows approval results.

Limits

Public endpoints are rate limited per IP (e.g. 6 submissions per minute per form). Submissions are limited to 512 KB of JSON.