API reference
Version v1
The formcel REST API lets you manage forms, submissions, folders and
webhook subscriptions in your workspace. Every request goes to your own
instance: your custom domain if one is configured, otherwise
{company}.formcel.com.
Versioning
The v1 contract is frozen: fields are only ever added, never renamed or removed. String fields that carry a status, role or type may gain new values over time, so treat unknown values as unknown instead of failing.
Pagination
List endpoints that accept limit (default 25, max 100) and offset
(default 0) return a page wrapped in {"data": [...], "total", "limit", "offset"}. Lists that are not paginated use the same envelope with every
item in data.
Errors
Errors return a non-2xx status and a body of the form
{"error": {"code": "not_found", "message": "Form not found"}}. Branch on
code; message is for humans and may change.
Event delivery
Subscribed events are POSTed as JSON with the headers X-Webhook-Event
(the event name) and X-Webhook-ID (the subscription ID). Respond with
any 2xx status within 10 seconds. Failed deliveries are retried twice,
after 4 and 16 seconds.
Base URL
Replace acme.formcel.com with your custom domain or your {company}.formcel.com host.
https://acme.formcel.com/api/v1Authentication
Send an API key as a Bearer token: Authorization: Bearer xf_... Create keys in Settings > API Keys; the full key is shown once. A key acts as the user who created it, with that user's access. Service account keys (xfs_...) work the same way but are limited to the scopes granted to the account; each operation lists the scope it requires.
curl "https://acme.formcel.com/api/v1/auth/me" \
-H "Authorization: Bearer $FORMCEL_API_KEY"Resources
- Authentication Verify credentials and choose the active workspace.
- Forms Create, update, publish and organise forms.
- Submissions Read and manage the responses collected by a form.
- Folders Group forms into folders.
- Workspaces List the workspaces you belong to and their members.
- Hooks REST hook subscriptions used by automation platforms (Zapier, Make). formcel POSTs a JSON payload to the target URL whenever the subscribed event happens.