API Reference

Endpoints, payloads, and status codes for FormFeeder API

reference
api reference endpoints rest

API Reference

Endpoints, payloads, and status codes.

Core Endpoints

FormFeeder provides two primary endpoints for form handling:

POST /v1/form/

Submit a form

Submit form data to be processed and forwarded to configured destinations. Supports JSON, form-encoded, and multipart data with file uploads.

Parameters

Name Type Description
formId string The unique identifier for your form (path parameter)

Request Headers

Name Value Required
Content-Type application/json For JSON payloads
Content-Type application/x-www-form-urlencoded For form-encoded data
Content-Type multipart/form-data For file uploads
Origin Your domain Yes (for CORS validation)

Request Body

The request body can be in any of these formats:

JSON Format:

{
  "name": "John Doe",
  "email": "[email protected]",
  "message": "Hello FormFeeder!"
}

Form-encoded:

name=John+Doe&[email protected]&message=Hello+FormFeeder!

Multipart (with files):

Content-Disposition: form-data; name="name"
John Doe

Content-Disposition: form-data; name="email"
[email protected]

Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf
[binary file content]

Response

Success (200 OK):

{
  "success": true,
  "message": "Form submitted successfully",
  "submissionId": "sub_abc123"
}

Error (4xx/5xx):

{
  "success": false,
  "message": "Error description",
  "code": "ERROR_CODE"
}

POST /v1/forms/from-email

Create private form from email

Programmatically create a private form that forwards submissions to an email address.

Request Body

{
  "email": "[email protected]",
  "allowedDomain": "https://www.example.com"
}

Parameters

Name Type Required Description
email string Yes Email address to receive form submissions
allowedDomain string Yes Domain allowed to submit to this form

Response

Success (201 Created):

{
  "formId": "pvt_abc123xyz",
  "allowedDomain": "https://www.example.com",
  "email": "[email protected]"
}

Status Codes

Success Codes

Code Description
200 Form submitted successfully
201 Private form created successfully

Client Error Codes

Code Description Common Causes
400 Bad Request Invalid form data, missing required fields
401 Unauthorized Domain not in allowed list, form not found
413 Payload Too Large File upload exceeds size limits
415 Unsupported Media Type Invalid Content-Type header
429 Too Many Requests Rate limit exceeded

Server Error Codes

Code Description
500 Internal Server Error
503 Service Unavailable

Rate Limiting

FormFeeder implements rate limiting to prevent abuse:

  • Global limit: 100 requests per minute per IP
  • Form-specific limit: Configurable per form (default: 10 per minute)

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

File Upload Limits

Default file upload limits (configurable per form):

  • Maximum file size: 5MB per file
  • Maximum total size: 10MB per submission
  • Maximum files: 5 files per submission

Supported file types:

  • Images: .jpg, .jpeg, .png, .gif, .webp
  • Documents: .pdf, .doc, .docx, .txt
  • Spreadsheets: .xls, .xlsx, .csv

CORS Policy

FormFeeder implements strict CORS policies:

Form Endpoints (`/v1/form/

  • Allowed Origins: Configured per form via allowedDomains
  • Allowed Methods: POST, OPTIONS
  • Allowed Headers: Content-Type, Authorization

Generic Endpoints

  • Allowed Origins: Configured globally
  • Allowed Methods: GET, POST, OPTIONS

Error Response Format

All error responses follow a consistent format:

{
  "success": false,
  "message": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": {
    "field": "Additional error details"
  }
}

Common Error Codes

Code Description
FORM_NOT_FOUND The specified form ID doesn't exist
DOMAIN_NOT_ALLOWED Origin domain not in form's allowed list
VALIDATION_ERROR Form data validation failed
FILE_TOO_LARGE Uploaded file exceeds size limit
RATE_LIMIT_EXCEEDED Too many requests from this IP

Request Examples

Basic Form Submission

curl -X POST "https://api.formfeeder.io/v1/form/abc123" \
  -H "Content-Type: application/json" \
  -H "Origin: https://example.com" \
  -d '{
    "name": "Alice Smith",
    "email": "[email protected]",
    "message": "This is a test message"
  }'

Form with File Upload

curl -X POST "https://api.formfeeder.io/v1/form/abc123" \
  -H "Origin: https://example.com" \
  -F "name=Alice Smith" \
  -F "[email protected]" \
  -F "resume=@/path/to/resume.pdf"

Create Private Form

curl -X POST "https://api.formfeeder.io/v1/forms/from-email" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "allowedDomain": "https://www.example.com"
  }'

Webhooks (Form Responses)

When forms are configured with webhooks, FormFeeder will send POST requests to your configured URL:

Webhook Payload

{
  "formId": "abc123",
  "submissionId": "sub_def456",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "name": "Alice Smith",
    "email": "[email protected]",
    "message": "This is a test message"
  },
  "files": [
    {
      "fieldName": "resume",
      "filename": "resume.pdf",
      "contentType": "application/pdf",
      "size": 1024000,
      "url": "https://files.formfeeder.io/temp/abc123/resume.pdf"
    }
  ],
  "metadata": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "referer": "https://example.com/contact"
  }
}

Webhook Security

  • Webhooks include an X-FormFeeder-Signature header for verification
  • Timeout: 30 seconds
  • Retry policy: 3 attempts with exponential backoff

On this page