API Reference
Complete technical reference for Static Forms API
Base URL
POST /submit
Submit form data to your Static Forms account.
Request
Content-Type
application/json- JSON payloads (for API requests)application/x-www-form-urlencoded- Standard HTML formsmultipart/form-data- Forms with file uploads
Required Parameters
| Parameter | Type | Description |
|---|---|---|
| apiKey | string | Your unique API key from the dashboard |
Optional Parameters
| Parameter | Type | Description |
|---|---|---|
| redirectTo | URL | URL to redirect after successful submission |
| honeypot | string | Honeypot field for spam protection (any field with "honeypot" in name, should be hidden) |
| replyTo | string | Reply-to email address (or use email field value) |
| g-recaptcha-response | string | reCAPTCHA response token (v2 widget field name) |
| recaptchaToken | string | reCAPTCHA token (v2 or v3) |
| altchaToken | string | ALTCHA challenge response (if enabled) |
Example Requests
JSON Request
Form-Encoded Request
Response
Success Response (200 OK)
Error Response (400 Bad Request)
Error Response (401 Unauthorized)
Status Codes & Error Responses
The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with error details.
| Code | Description | Common Causes |
|---|---|---|
| 200 | Success - Form submission received and processed | Valid submission |
| 400 | Bad Request - Missing required fields or invalid data | Missing apiKey, invalid file type, file too large |
| 401 | Unauthorized - Invalid or missing API key | Wrong API key, API key not provided |
| 403 | Forbidden - Account suspended or tier restriction | Account suspended, feature requires Pro tier |
| 429 | Too Many Requests - Rate limit exceeded | Monthly limit exceeded, ALTCHA rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end | Server error, temporary service issue |
Error Response Examples
400 Bad Request - Missing API Key
400 Bad Request - File Too Large
401 Unauthorized - Invalid API Key
403 Forbidden - Feature Requires Pro Tier
429 Too Many Requests - Monthly Limit Exceeded
429 Too Many Requests - ALTCHA Rate Limit
💡 Need Help? Check out our troubleshooting guide for solutions to common errors.
Rate Limits
Static Forms uses monthly email limits to prevent abuse while ensuring reliable service:
Monthly Email Limits
Form submissions are limited by monthly email sending quotas:
| Plan | Emails/Month | Notes |
|---|---|---|
| Free | 500 | Resets monthly |
| Pro | 25,000 | Resets monthly |
💡 Note: Monthly limits apply to successful form submissions that result in emails being sent. If you exceed your monthly limit, you'll receive a 429 status code.
Per-Minute Rate Limits
The ALTCHA challenge endpoint has per-minute rate limiting:
- ALTCHA Challenge Endpoint: 10 requests per minute per API key
- Form Submission Endpoint: No per-minute rate limiting (only monthly limits apply)
⚠️ Note: Rate limits are applied per API key. If you exceed your limit, you'll receive a 429 status code with an error message.
CORS Support
The Static Forms API supports Cross-Origin Resource Sharing (CORS), allowing you to make requests from any domain.
💡 Info: All origins are allowed for form submissions. No additional configuration is required.
Special Field Names
Certain field names have special handling:
honeypot- Any field containing "honeypot" in the name is used for spam detection and removed from emailsreplyTo- Custom reply-to email addressemail- Used as reply-to if replyTo is not providedredirectTo- URL to redirect after successful submission
All other field names are treated as regular form data and will be included in your notification email.
Code Examples
JavaScript (Fetch API) - JSON
JavaScript (Fetch API) - FormData
cURL - JSON
cURL - Form Data
Python (Requests) - JSON
Python (Requests) - Form Data