API Reference

REST API

Complete API documentation for form submissions. All endpoints support JSON and form-urlencoded data.

Submit Form

POST/f/{formId}

Request Headers

Header	Value	Required
`Content-Type`	`application/json` or `application/x-www-form-urlencoded` or `multipart/form-data`	Yes

Request Body

Any JSON object with your form fields:

JSON

{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Hello, world!",
  "phone": "+1234567890"
  // ... any other fields
}

Responses

200Success

JSON

{
  "success": true,
  "message": "Thank you for your submission!",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

404Not Found

JSON

{ "error": "Form not found" }

403Forbidden

JSON

{ "error": "Form is not accepting submissions" }

400Bad Request

JSON

{ "error": "Empty submission" }
// Or
{ "error": "Submission contains potentially malicious content" }

CORS

All form endpoints support CORS and can be called from any domain. The following headers are set:

Response Headers

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Rate Limiting

Form submissions are rate-limited per form. Default limits apply to prevent abuse. Contact us if you need higher limits.

Plan	Rate Limit	Per
Free	50 submissions	per month
Pro	5,000 submissions	per month
Enterprise	Unlimited	-

cURL Examples

JSON Request

bash

curl -X POST https://townhall.gg/f/YOUR_FORM_ID \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","message":"Hello!"}'

Form URL-Encoded

bash

curl -X POST https://townhall.gg/f/YOUR_FORM_ID \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=John%20Doe&email=john@example.com&message=Hello!"

Form Features

Email Notifications

Add multiple email addresses to receive form submissions. Each recipient gets their own copy with:

All form fields formatted nicely

Submission metadata (IP, timestamp, etc.)

Direct link to view in dashboard

Email open tracking (see who opened)

Auto-Reply

Automatically send a confirmation email to the person who submitted the form:

From Name: The name shown in recipient's inbox

Subject: Email subject line

Message: Your custom message (supports {name} placeholder)

🎯

Smart Email Detection

We automatically find email addresses from any field in the submission. No specific field name required!

Security

TownHall includes built-in security measures to protect your forms:

Code/script injection detection and blocking

SQL injection pattern detection

XSS attack prevention

Rate limiting per form