API Reference

Invalid or missing API key. The request has no Authorization header, or the key doesn't match any active key.

Common causes:

• Missing Authorization: Bearer fb_sk_... header
• Key was deleted from the API Keys page
• Key was not fully copied (only shown once on creation)

You don't have permission for this action. Multiple possible causes:

The resource doesn't exist or doesn't belong to your account. Form IDs, submission IDs, and file names are scoped to your account — you cannot access other users' data.

A file upload exceeds your plan's limits:

Delete old submissions or files to free space, or upgrade.

The request body is malformed or missing required fields. Check the endpoint documentation for the expected fields and types.

Monthly submission limit reached. This applies to form submissions via POST /f/{endpoint_id}, not to API management calls.

• Resets on the 1st of each month at midnight UTC
• Count is across all your forms combined, not per form
• Spam-flagged submissions still count (they were accepted before being flagged)
• Check usage: GET /api/forms/stats → submissions_this_month vs submissions_limit

List all your forms with submission counts (excludes spam).

curl -H "Authorization: Bearer fb_sk_..." \
  https://formblade.com/api/forms

Response: Array of form objects (see fields above).

Create a new form. Returns 201 Created.

curl -X POST -H "Authorization: Bearer fb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact Form", "notify_email": "you@example.com"}' \
  https://formblade.com/api/forms

Request body:

Response: Form object.

Get a single form by ID.

Path: form_id — uuid (required)

Response: Form object.

Update form settings. Send only the fields you want to change.

curl -X PATCH -H "Authorization: Bearer fb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "is_active": false}' \
  https://formblade.com/api/forms/{form_id}

Request body (all optional):

Response: Updated form object.

Delete a form and all its submissions and files. This action is irreversible.

Response: 204 No Content

Dashboard statistics: submission counts, storage usage, recent activity.

{
  "total_forms": 3,
  "total_submissions": 150,
  "submissions_today": 5,
  "submissions_this_week": 28,
  "submissions_this_month": 95,
  "spam_count": 4,
  "storage_used_mb": 12.5,
  "storage_limit_mb": 50,
  "submissions_limit": 300,
  "forms_limit": 5,
  "plan": "free",
  "recent_submissions": [...],
  "top_forms": [...]
}

Send a test notification email using the form's email configuration.

{"ok": true, "message": "Test email sent to you@example.com"}

List submissions with pagination and spam filtering.

curl -H "Authorization: Bearer fb_sk_..." \
  "https://formblade.com/api/forms/{form_id}/submissions?page=1&per_page=25&spam=false"

Response:

{
  "items": [
    {
      "id": "106f069f-...",
      "data": {"name": "Jane", "email": "jane@example.com", "message": "Hello!"},
      "files": null,
      "ip_address": "203.0.113.42",
      "device": {"device_type": "desktop", "browser": "Chrome 145.0.0", "os": "Windows 10"},
      "is_spam": false,
      "spam_flags": null,
      "created_at": "2026-03-23T11:02:05Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 25
}

Export submissions as CSV, JSON, or Excel. Excludes spam. Returns a file download.

curl -H "Authorization: Bearer fb_sk_..." \
  -o submissions.csv \
  "https://formblade.com/api/forms/{form_id}/submissions/export?format=csv"

Toggle the spam flag on a submission. Returns the new state.

{"ok": true, "is_spam": true}

Resend the notification email for a submission.

{"ok": true, "message": "Notification resent to you@example.com"}

Delete a submission and its uploaded files.

Response: 204 No Content

Download an uploaded file. The stored_name comes from the submission's files object.

curl -H "Authorization: Bearer fb_sk_..." \
  -o document.pdf \
  https://formblade.com/api/forms/{form_id}/submissions/{id}/files/{stored_name}

List all uploaded files across your forms with filtering and pagination.

Most likely a scope or plan issue. Check these in order:

1. Are you on the Personal plan making a write request? Personal accounts can only use GET endpoints. POST/PATCH/DELETE require a Pro plan with a full-scoped key.
2. Did you create a read-only key? Even on Pro, if you created a read key it will reject write requests. Create a new full key from API Keys.
3. Are you trying to use a Pro feature? Some form settings (certain captcha providers, auto-responder, custom theme colors) require a Pro plan even with a full-access key.

The key doesn't match. Verify:

• Header format is exactly Authorization: Bearer fb_sk_... (with space after Bearer)
• You copied the full key when it was shown (it's only displayed once)
• The key hasn't been deleted or disabled in API Keys
• No extra whitespace or line breaks in the key

The monthly limit counts submissions across all your forms combined, not per form. Spam-flagged submissions also count because they were accepted before being flagged.

Check your usage: GET /api/forms/stats returns submissions_this_month and submissions_limit.

Limits: Personal 300/month, Pro 3,000/month. Resets on the 1st at midnight UTC.

Two possible causes:

• Single file too large — Personal: 1 MB max, Pro: 25 MB max
• Total storage full — Personal: 100 MB, Pro: 1 GB. Delete old submissions or files to free space.

Check storage usage via GET /api/forms/stats → storage_used_mb and storage_limit_mb.

New forms get default fields (name, email, message) automatically. If you want custom fields, set form_fields in a follow-up PATCH request with your field configuration array.