API Reference

Use the StaticForm REST API to submit forms, list submissions, manage forms, and automate everything from your own scripts.

View .md
On this page

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:

api.staticform.app/scalar

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:

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-urlencoded or multipart/form-data. A JSON body is rejected with 400.
  • CORS: any origin may post, so a browser fetch from 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: 200 with { "values": { ... } }. If the form has a success redirect, a plain browser post gets a 302 to that URL, and a request with the header X-Requested-With: XMLHttpRequest gets 200 with { "redirectUrl": "...", "status": "success", "message": "..." } instead.
  • Failure: 400 with Problem Details and an errors array of { name, reason, code, severity }, one entry per failing field (see Form Configuration). 404 for an unknown form, 402 when the form is temporarily unavailable (the owner’s plan ended more than 14 days ago, or no storage is left), 413 for an oversized request and 429 when 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 still 200 OK and 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. The errors property maps each field name to its messages, and errorCode names the failure. The public submission endpoint is the exception: its errors is an array of { name, reason, code, severity } entries.
  • Authentication failures return 401 Unauthorized; missing permissions return 403 Forbidden. A key restricted to other forms gets 403 for 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 Requests with errorCode: "RateLimited", a retryAfter timestamp and a Retry-After header 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.