API Documentation

Endpoint

All form submissions are sent to a single endpoint:

POST https://catchform.dev/f/{token}

Replace {token} with your form's unique token, shown in the dashboard after creating a form.

Request Format

Send form data as application/x-www-form-urlencoded or multipart/form-data (for file uploads):

<form action="https://catchform.dev/f/your-token"
      method="POST">
  <input name="email" type="email">
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

Field names are arbitrary — you define them in your HTML. All fields are optional; an empty form is valid.

For a complete walkthrough of building an HTML form for email delivery, see our guide on connecting HTML forms to email.

Special Fields

<input type="hidden" name="_gotcha" value="">

<input type="hidden" name="_redirect" value="https://example.com/thank-you">

Response Format

Responses vary based on your form's redirect settings and on how the request was made:

{"success": true}

{"error": "Monthly limit exceeded"}

Submission Limits

Each plan includes a monthly submission quota. Once exceeded, new submissions are rejected until the next month or until you upgrade:

File Uploads

File uploads are available on the Starter and Pro plans. Each file must meet these requirements:

• • Maximum size: 5 MB
• • Allowed types: JPEG, PNG, GIF, PDF

If file uploads are submitted to a Free plan account, the submission is still accepted but files are not stored. The submission data will include a note that attachments were not saved.

Webhooks

Webhooks are available on the Pro plan. When a submission is received, CatchForm sends an HTTP POST to each active webhook URL with the following payload:

{
  "form_id": 42,
  "submission_id": 1337,
  "data": { /* submitted fields */ },
  "submitted_at": "2026-01-15T10:30:00.000000Z"
}

If you configured a webhook secret, each request includes an X-Webhook-Signature header containing an HMAC-SHA256 hash of the JSON payload, allowing you to verify the request's authenticity.

Email Notifications

When you create a form, you provide an email address where submissions should be delivered. Before the first submission is sent, we verify that you own this email address by sending a confirmation link.

Each email notification includes the submission data. The email's Reply-To header is set to the email field from the submission (if present), allowing you to reply directly to the form's author.

MCP Server

MCP (Model Context Protocol) allows AI agents like Claude to manage forms and read submissions through CatchForm. Connect an AI assistant to create forms, retrieve data, and process submissions — and it's free on every plan, including Free.

Getting your API token

Visit your account settings, find the API tokens section, and create a new token. The value is shown only once — copy it immediately.

Configuration

The server runs on our side — there is nothing to install. Point your client at the URL below and pass your token. In Claude Code:

claude mcp add --transport http catchform https://catchform.dev/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Clients that keep servers in a JSON file — Cursor among them — take the same two values:

{
  "mcpServers": {
    "catchform": {
      "type": "http",
      "url": "https://catchform.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

The token is a normal CatchForm API token, so the agent sees exactly what your account sees — its own forms and their submissions, nothing else. Revoke it on the account page and the agent loses access immediately.

Available tools

• • list-forms — your forms with their endpoint URLs
• • get-form — one form: endpoint, notification address, redirect, ready HTML snippet
• • create-form — create a form; a confirmation link goes to the notification address
• • list-submissions — submissions of a form, newest first, with optional search

Feeding these docs to an AI agent

Two plain-text files exist for that: /llms.txt is a short map of the site, and /llms-full.txt is this documentation, the guides and the comparisons as one text. Both are generated from the pages you are reading, so they cannot drift out of date. Paste either URL into Cursor, Claude Code or any assistant that reads links, or connect the MCP server above and skip the copying.

Clients and read-only links

Group your forms by client and share a unique read-only link for each client to view their submissions. No account required — the link gives direct access.

Group forms by client

A Client is a grouping for your forms. Create clients in the Clients section of your dashboard. Each client has a name (up to 80 characters). When you create or edit a form, assign it to a client or leave it unassigned. Each client displays how many forms it contains and the number of submissions received in the last 30 days.

Deleting a client does not delete its forms or submissions — they remain in your account, unassigned to any client.

Share a read-only link

On a client's page, create a read-only link. The link uses a random token (48 characters) that you can share with anyone — no password needed. They see the submissions for all forms assigned to that client, newest submissions first, with search and pagination included. You can generate multiple links for the same client and revoke them individually. After revocation, the link returns a 404 for any future visit, as if it never existed.

Each link tracks when it was last visited, so you know if your client is still checking their submissions.

What the client sees — and what they do not

The client can see:

• • All submissions for forms in their client, newest first
• • Search by submission data
• • Pagination through submissions

The client cannot see or do:

• • Delete or edit submissions
• • Change form settings or create new forms
• • Access your account
• • Download file attachments — instead they see "attachment available to the account owner"
• • View the IP address or user agent of the person who submitted

The page is hidden from search engines (marked with noindex) and restricted to prevent abuse.

Learn More

Need implementation examples? Check out our guides:

• • HTML form to email — The simplest integration
• • Contact form for Astro — Astro-specific example
• • Contact form for Hugo — Hugo template example
• • Contact form without PHP — Replace a contact.php script
• • Static site contact form — Host-by-host breakdown

Questions? Get in touch.