Documentation

Quick Start Basic Setup API Reference Spam Protection Advanced Features Framework Examples Troubleshooting FAQ

API Reference

Complete technical reference for Static Forms API

Base URL

https://api.staticforms.xyz

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 forms
multipart/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 (if enabled)
altcha	string	ALTCHA challenge response (if enabled)

Example Requests

JSON Request

POST /submit HTTP/1.1
Host: api.staticforms.xyz
Content-Type: application/json

{
  "apiKey": "your_api_key_here",
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Hello, I would like to get in touch."
}

Form-Encoded Request

POST /submit HTTP/1.1
Host: api.staticforms.xyz
Content-Type: application/x-www-form-urlencoded

apiKey=your_api_key_here
&name=John+Doe
&email=john@example.com
&message=Hello%2C+I+would+like+to+get+in+touch.

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Form submission received"
}

Error Response (400 Bad Request)

{
  "success": false,
  "message": "API key is required"
}

Error Response (401 Unauthorized)

{
  "success": false,
  "message": "Invalid API key"
}

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

{
  "success": false,
  "message": "API key is required"
}

400 Bad Request - File Too Large

{
  "success": false,
  "message": "File "document.pdf" is too large (6.2MB). Maximum allowed size is 5MB."
}

401 Unauthorized - Invalid API Key

{
  "success": false,
  "message": "Invalid API key"
}

403 Forbidden - Feature Requires Pro Tier

{
  "success": false,
  "message": "File uploads require Pro tier. Please upgrade your plan."
}

429 Too Many Requests - Monthly Limit Exceeded

{
  "success": false,
  "message": "Monthly email limit (500) exceeded for your account tier (free). Please upgrade your plan to send more emails."
}

429 Too Many Requests - ALTCHA Rate Limit

{
  "error": "Rate limit exceeded. Please try again later."
}

💡 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 emails
replyTo - Custom reply-to email address
email - Used as reply-to if replyTo is not provided
redirectTo - 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

const response = await fetch('https://api.staticforms.xyz/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    apiKey: 'YOUR_API_KEY',
    name: 'John Doe',
    email: 'john@example.com',
    message: 'Hello!'
  })
});

const data = await response.json();
console.log('Success:', data);

JavaScript (Fetch API) - FormData

const formData = new FormData();
formData.append('apiKey', 'YOUR_API_KEY');
formData.append('name', 'John Doe');
formData.append('email', 'john@example.com');
formData.append('message', 'Hello!');

fetch('https://api.staticforms.xyz/submit', {
  method: 'POST',
  body: formData
})
  .then(response => response.json())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

cURL - JSON

curl -X POST https://api.staticforms.xyz/submit \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello!"
  }'

cURL - Form Data

curl -X POST https://api.staticforms.xyz/submit \
  -d "apiKey=YOUR_API_KEY" \
  -d "name=John Doe" \
  -d "email=john@example.com" \
  -d "message=Hello!"

Python (Requests) - JSON

import requests

data = {
    'apiKey': 'YOUR_API_KEY',
    'name': 'John Doe',
    'email': 'john@example.com',
    'message': 'Hello!'
}

response = requests.post(
    'https://api.staticforms.xyz/submit',
    json=data
)

print(response.json())

Python (Requests) - Form Data

import requests

data = {
    'apiKey': 'YOUR_API_KEY',
    'name': 'John Doe',
    'email': 'john@example.com',
    'message': 'Hello!'
}

response = requests.post(
    'https://api.staticforms.xyz/submit',
    data=data
)

print(response.json())