Integration
API Reference
Use the StaticForm REST API to submit forms, list submissions, manage forms, and automate everything from your own scripts.
On this page
- Interactive API Docs
- Base URL
- Authentication
- 1. API Key (recommended for scripts & integrations)
- 2. Browser session (used by the dashboard)
- Public endpoint: form submission
- Quick Examples
- Submit a form (public, no auth)
- List your forms (requires API key)
- List submissions for a form
- Count unread submissions per form
- Export submissions as JSON
- Create a form
- What You Can Do With the API
- Using an AI agent instead
- Rate Limits & Errors
- OpenAPI Specification
- Need Help?
StaticForm exposes a REST API that powers both the dashboard and external integrations. You can use it to automate form management, pull submissions into your own systems, or build custom tooling on top of the product.
Interactive API Docs
The full API reference is available as an interactive explorer at:
It includes every endpoint with request/response schemas, authentication details, and the ability to try API calls directly from your browser. The reference is powered by Scalar and generated from the OpenAPI spec.
Base URL
API endpoints are versioned and follow this pattern:
https://api.staticform.app/api/v{version}/...
The current version for most endpoints is v1. Check the interactive API docs for the exact version of each endpoint.
Authentication
There are two ways to authenticate with the API:
1. API Key (recommended for scripts & integrations)
Create an API key from Settings → API keys in the dashboard (see Account Settings). The plain key is shown only once, so copy it immediately.
Pass the key in the X-API-Key header on every request:
X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
An API key carries the self-service permissions of the user who created it, or the narrower set you pick when you create it. Staff and admin permissions never apply to a key, and a key can be restricted to specific forms or workspaces. Keys can be revoked at any time from the dashboard. Set an expiration date when creating the key if you want it to roll over automatically.
2. Browser session (used by the dashboard)
The dashboard signs you in with a session cookie, and every request that changes data also carries an X-CSRF-Token header. API key requests need no CSRF token.
This flow is intended for browser sessions. For programmatic use, prefer API keys.
Public endpoint: form submission
The form submission endpoint (POST /api/v1/forms/{formId}) is public and does not require authentication: that’s what lets your static HTML forms post to it directly. Every other endpoint requires an API key or a signed-in session.
What the public endpoint does:
- Content types:
application/x-www-form-urlencodedormultipart/form-data. A JSON body is rejected with400. - CORS: any origin may post, so a browser
fetchfrom your own site works. - Limits: 60 requests per minute per IP address, 30 MB per request, at most 20 uploaded files per request and 25 MB per file.
- Success:
200with{ "values": { ... } }. If the form has a success redirect, a plain browser post gets a302to that URL, and a request with the headerX-Requested-With: XMLHttpRequestgets200with{ "redirectUrl": "...", "status": "success", "message": "..." }instead. - Failure:
400with Problem Details and anerrorsarray of{ name, reason, code, severity }, one entry per failing field (see Form Configuration).404for an unknown form,402when the form is temporarily unavailable (the owner’s plan ended more than 14 days ago, or no storage is left),413for an oversized request and429when you post too often.
Quick Examples
Submit a form (public, no auth)
curl -X POST https://api.staticform.app/api/v1/forms/YOUR_FORM_ID \
--data-urlencode "name=Ada Lovelace" \
--data-urlencode "email=ada@example.com" \
--data-urlencode "message=Hello from the API!"
The submission endpoint accepts application/x-www-form-urlencoded or multipart/form-data (required for file uploads). JSON bodies are not supported. See Form Configuration for field types and validation rules.
Important: The example above is shown for reference, but a submission sent with
curl(or Postman, HTTPie,python-requests,axios, and similar clients) to a client-side form will almost certainly be classified as spam. StaticForm’s request header analysis expects real browser headers, so the response is still200 OKand the submission is stored, but it goes to the spam list and no email notification or webhook fires. To check that a form works, submit it from a real browser rather than from the command line. See Spam Protection for details.
List your forms (requires API key)
curl "https://api.staticform.app/api/v1/forms?pageNumber=1&pageSize=25" \
-H "X-API-Key: $STATICFORM_API_KEY"
List submissions for a form
curl https://api.staticform.app/api/v1/forms/YOUR_FORM_ID/submissions \
-H "X-API-Key: $STATICFORM_API_KEY"
Count unread submissions per form
curl "https://api.staticform.app/api/v1/submissions/counts?formIds=YOUR_FORM_ID" \
-H "X-API-Key: $STATICFORM_API_KEY"
Returns the unread and total number of inbox and spam submissions for each form, plus the totals, and no submission data. Repeat formIds for more forms (at most 100), or leave it out for every form the key can reach. The key needs the User.Submissions.GetCounts permission, which the WordPress template includes.
Export submissions as JSON
curl https://api.staticform.app/api/v1/forms/YOUR_FORM_ID/submissions/export/json \
-H "X-API-Key: $STATICFORM_API_KEY" \
-o submissions.json
Create a form
curl -X POST https://api.staticform.app/api/v1/forms \
-H "X-API-Key: $STATICFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Contact Form",
"fields": [
{ "name": "email", "type": "Text", "rule": "Email", "required": true },
{ "name": "message", "type": "Text", "rule": "None", "required": true }
],
"submitActions": [
{
"type": "SendEmailAction",
"name": "Email notification",
"recipient": "you@example.com",
"subject": "New submission from {{formName}}",
"bodyTemplate": "{{submissionData}}"
}
]
}'
What You Can Do With the API
Anything you can do in the dashboard, you can do via the API. Common use cases:
- Pull submissions into your CRM, data warehouse, or internal tools
- Create and update forms programmatically (e.g., from infrastructure-as-code)
- Sync submissions to another system on a schedule
- Build custom dashboards or reporting on top of your form data
- Automate cleanup: delete old submissions, rotate forms, mark spam
- Manage collaborators on forms from your own admin tooling
The full list of endpoints (forms, submissions, submit actions, email attachments, execution logs, collaborators, invitations, billing, and user settings) is available in the interactive API docs.
Using an AI agent instead
If you want an AI agent such as Claude, ChatGPT, Claude Code, or Cursor to work with your forms, you don’t need to write API calls yourself. Add the StaticForm MCP server to your AI app, approve access in the browser, and ask it to build forms, summarize your leads, or tell you what people submit most. For headless agents, the MCP server also accepts the same API keys as the REST API, with the same permissions and form access.
Rate Limits & Errors
- The API uses RFC 7807 Problem Details for error responses.
- Validation failures return
400 Bad Request. Theerrorsproperty maps each field name to its messages, anderrorCodenames the failure. The public submission endpoint is the exception: itserrorsis an array of{ name, reason, code, severity }entries. - Authentication failures return
401 Unauthorized; missing permissions return403 Forbidden. A key restricted to other forms gets403for a form outside its scope. - Requests are limited to 600 per minute per user, with stricter limits on sensitive endpoints such as creating API keys (10 per minute). Form submissions are limited to 60 per minute per IP address.
- When you exceed a limit the API answers
429 Too Many RequestswitherrorCode: "RateLimited", aretryAftertimestamp and aRetry-Afterheader in seconds. Wait that long before trying again, because rejected requests still count.
OpenAPI Specification
The raw OpenAPI JSON spec is available at:
https://api.staticform.app/openapi/v1.json
You can use this to:
- Generate client libraries in your language of choice (e.g., with openapi-generator)
- Import into Postman or Insomnia
- Integrate with any OpenAPI-compatible tooling
- Type-check API calls in TypeScript projects
Need Help?
If you’re building something with the API and get stuck, contact us. We’re happy to help.