FormWork documentation
API Reference
Find the OpenAPI specification and the main API areas available for integrations.
The FormWork API is available for teams that need custom integrations, reporting, migrations, or developer-built workflows around FormWork data.
Most users do not need to use the API directly. Start with the builder, workflows, extensions, API Connectors, imports, and exports before building a direct integration.
Interactive API Docs
Use the interactive OpenAPI documentation for full endpoint details, request fields, and response examples.
Explore every endpoint
Browse request fields, schemas, authentication details, and response examples in the generated OpenAPI reference.
OpenAPI Specification
| Format | URL |
|---|---|
| JSON | openapi.json |
| YAML | openapi.yaml |
Authentication
API keys are managed from account settings.
Send the key in the Authorization header and identify its account with X-Account-ID on account-scoped routes:
curl "https://app.useformwork.com/api/v1/projects" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Account-ID: YOUR_ACCOUNT_ID"See API Keys for creating and managing keys.
The account header must match the key’s account. The key uses the identity and account role of its creator, so it cannot bypass Admin-only endpoint checks.
Respondent entry-session endpoints use X-Formwork-Entry-Key after an entry is created. Do not expose account API keys in browser code or use an entry key as account authentication.
Base URL and errors
The production base is:
https://app.useformwork.com/api/v1Successful list responses commonly contain data and pagination metadata. Errors return an HTTP status plus a stable error code and message. Handle at least authentication/forbidden responses, validation errors, 402 billing_inactive, not-found responses, conflict-style state errors, and transient server/network failures according to the endpoint contract.
Main API Areas
| Area | What it is for |
|---|---|
| Accounts and users | Manage account details, users, roles, and account switching. |
| Billing | Read billing status and create checkout or billing portal sessions. |
| Projects | Create and manage projects. |
| Forms and form versions | Create forms, edit drafts, validate versions, publish, and manage fields. |
| Entry sessions | Public form rendering, answer updates, repeatable groups, submission, buttons, draft resume, and upload flow. |
| Entries and revisions | Admin entry management, answers, metafields, files, edit sessions, revisions, and workflow runs. |
| Data tables | Create tables and manage rows for structured operational data. |
| Workflows | Manage workflow definitions, triggers, steps, connections, runs, and run details. |
| References | Search and resolve references used by workflows, templates, and mappings. |
| Views, imports, and exports | Saved entry views, CSV imports, exports, and background job tracking. |
| Files and jobs | Prepare uploads, complete uploads, download files, and track background jobs. |
| Extensions | Manage installed extensions, API Connectors, environments, secrets, actions, and webhooks. |
| Templates | Manage reusable content and layout templates. |
Public Form Endpoints
Embedded forms use public entry-session endpoints behind the scenes. These endpoints support:
- Loading a public form schema before an entry exists
- Creating a draft entry
- Updating answers
- Adding and removing repeatable group instances
- Submitting an entry
- Handling button clicks
- Supporting draft resume flows
- Uploading files
- Calling entry-scoped extension actions
For normal embeds and host-page coordination, use the Web Component & JavaScript API instead of calling these endpoints directly. Use the entry-session endpoints when you are deliberately building and maintaining your own complete form interface.
When to Use the API
Use the API when you need to:
- Move data between FormWork and another system
- Build custom reporting
- Create or update entries from another application
- Automate project or form setup
- Connect a process that is too specific for a no-code workflow alone
Use an API Connector when an external service should be called from a workflow step. Use the REST API when the external system needs to manage FormWork data directly.