CatchForm

API Documentation

Technical reference for integrating CatchForm with your forms. Everything you need to know about endpoints, parameters, and responses.

← Back to home

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.

Special Fields

Honeypot (spam protection)

Add a hidden field named _gotcha to your form. Leave it empty. If a submission contains a non-empty value for this field, it will be rejected as spam: 

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

Spam detection response: 422 status with {"success": false, "message": "Spam detected."}

Redirect (optional)

Control where the user is redirected after submission using _redirect: 

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

For security, _redirect is only accepted if its host and scheme match the redirect URL configured in your form settings. Give it an absolute URL — a relative path like /thank-you carries no host, so it is ignored. Whenever the value is not accepted, the form's configured redirect is used instead, and the submission is still saved.

Response Format

Responses vary based on your form's redirect settings:

No redirect configured

Status: 200

{"success": true}

Redirect configured

Status: 302 (redirect to configured URL)

Invalid or inactive token

Status: 404

Monthly limit exceeded

Status: 429

{"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:

Free

100 submissions/month

Pro

10,000 submissions/month

File Uploads

File uploads are available on the Pro plan. 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.

Learn More

Need implementation examples? Check out our guides:

Questions? Get in touch.