API Documentation

Complete reference for integrating SeagullForm into your website. Get up and running in minutes.

Quick Start

Point your HTML form to your SeagullForm endpoint. That's all you need to get started.

Step 1: Get your endpoint

Create a form in the dashboard. Copy the endpoint ID.

Step 2: Add to your HTML

code

<form action="https://seagullform.com/api/submit/YOUR_ENDPOINT_ID" method="POST">
  <input name="email" type="email" required>
  <input name="message" required>
  <button type="submit">Send</button>
</form>

Step 3: Add spam protection

Add a hidden honeypot field. Bots fill it, humans don't.

code

<input type="text" name="_website" style="display:none" tabindex="-1" autocomplete="off">

Next.js Example

For JavaScript apps, send JSON requests to handle form submissions programmatically.

code

async function handleSubmit(e) {
  e.preventDefault();
  
  const res = await fetch("https://seagullform.com/api/submit/YOUR_ENDPOINT_ID", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: e.target.email.value,
      message: e.target.message.value,
    }),
  });
  
  if (res.ok) {
    // Success
  }
}

Response

code

{ "success": true }

Form Settings

Configure these settings in your dashboard to customize form behavior.

Setting	Description
name	Display name in dashboard
notificationEmail	Email for new submission alerts
successRedirectUrl	Redirect here after success (optional)
errorRedirectUrl	Redirect here on error (optional)
retentionDays	Days to keep submissions (default: 30)

Error Codes

Understand API responses and troubleshoot issues.

Code	Description
200	Submission accepted
302	Redirect (if successRedirectUrl set)
400	Invalid request body or content type
403	Monthly submission limit reached
404	Form not found (invalid endpoint ID)
429	Rate limit exceeded (10 req/min per IP)

Rate limit headers

code

X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1704067200000

Rate Limits & Quotas

Plan-based limits and rate limiting information.

Limit	Free	Basic	Pro
Projects	1	5	∞
Forms per project	1	10	∞
Submissions/month	50	1,000	∞

Rate limiting: 10 requests/minute per IP per form

Request body size: 1 MB max

Security & Privacy

Data we collect

✓Form field data you submit
✓IP address of submitter
✓User agent (browser)
✓Timestamp

Spam protection

✓Honeypot fields: _website, _company
✓Blocked fields: password, card, ssn, credit_card
✓IP-based rate limiting

Data retention

Submissions auto-delete after retentionDays (default: 30). Configure per form. Deleted data is not recoverable.

Encryption

✓TLS 1.2+ for all connections
✓Data encrypted at rest

See Privacy Policy and DPA for full details.

Ready to get started?

Start building with SeagullForm today. No credit card required.

Start Free →