REST API & API Keys

The authenticated REST API lets applications and AI agents list and manage forms or read stored responses. This is separate from the public submission endpoint documented in API Submissions.

Create an API key

1. Open Dashboard → Settings → API Keys.
2. Select Create Secret Key and give it a recognizable name.
3. Copy the token immediately. The complete token is shown only once.

You can keep up to five API keys. Revoking a key takes effect immediately and breaks clients still using it.

Treat keys like passwords: keep them on the server, do not commit them, and never expose them in browser JavaScript.

Authentication

Send the key as a Bearer token:

curl https://formbuild.io/api/v1/forms \
  -H "Authorization: Bearer formbuild_live_YOUR_KEY"

Authenticated API requests are limited to 100 requests per user per minute. A request without a valid key returns 401; exceeding the limit returns 429.

List forms

GET /api/v1/forms?limit=50&offset=0

limit is clamped to 1–100. The response includes data and pagination metadata containing total, limit, offset, and hasMore.

Create a form

POST /api/v1/forms
Content-Type: application/json

{
  "name": "Contact form",
  "fields": [
    { "name": "email", "label": "Email", "type": "email", "required": true },
    { "name": "message", "label": "Message", "type": "textarea", "required": true }
  ],
  "webhooks": ["https://example.com/webhooks/formbuild"]
}

Supported field types are text, email, textarea, number, select, and file. A request can include up to 50 fields and five HTTPS webhook URLs. Binary file storage is not currently supported even if a field is declared as file.

The normal plan limits and team permissions still apply to API-created forms.

Read, replace, or delete a form

Use either the internal form ID or public form ID:

GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

PUT accepts name, fields, and webhooks. Supplying fields or webhooks replaces the complete existing collection.

To protect against accidental data loss, deleting a form with stored responses returns 409. After confirming that permanent deletion is intended, repeat the request with ?force=true:

DELETE /api/v1/forms/{id}?force=true

List responses

GET /api/v1/forms/{id}/submissions?limit=50&offset=0

The endpoint returns active responses in newest-first order. Trashed responses are excluded. Each item contains the response ID, parsed data, isSpam, and createdAt.

Public submissions versus management API

For public JSON or FormData submissions, CORS, idempotency keys, and validation errors, see API Submissions.