Quick Reference Guide

A quick reference for common FiraForm tasks, code snippets, and configurations.

🎯 Essential URLs

Dashboard:        https://a.firaform.com
Form Endpoint:    https://a.firaform.com/api/f/{FORM-ID}
CAPTCHA Script:   https://a.firaform.com/captcha/{FORM-ID}

📋 Common Code Snippets

Basic HTML Form

<form action="https://a.firaform.com/api/f/YOUR-FORM-ID" method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <textarea name="message"></textarea>
  <button type="submit">Submit</button>
</form>

Form with CAPTCHA

<form action="https://a.firaform.com/api/f/YOUR-FORM-ID" method="POST">
  <input type="email" name="email" required>
  <script src="https://a.firaform.com/captcha/YOUR-FORM-ID"></script>
  <button type="submit">Submit</button>
</form>

JavaScript/Ajax Submission

fetch('https://a.firaform.com/api/f/YOUR-FORM-ID', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com'
  })
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

File Upload Form

<form action="https://a.firaform.com/api/f/YOUR-FORM-ID" 
      method="POST" 
      enctype="multipart/form-data">
  <input type="text" name="name" required>
  <input type="file" name="resume" accept=".pdf,.doc,.docx">
  <button type="submit">Submit</button>
</form>

Honeypot Field (Bot Protection)

<!-- Add this hidden field to catch bots -->
<input type="text" 
       name="website" 
       value="" 
       style="display:none" 
       tabindex="-1" 
       autocomplete="off">

Custom CAPTCHA Styling

<script>
window.FiraformCaptchaConfig = {
  width: '100%',
  height: '50px',
  primaryColor: '#4CAF50',
  backgroundColor: '#f0f0f0',
  borderRadius: '25px',
  labelText: 'Slide to verify'
};
</script>
<script src="https://a.firaform.com/captcha/YOUR-FORM-ID"></script>

Handle Validation Errors

fetch('https://a.firaform.com/api/f/YOUR-FORM-ID', {
  method: 'POST',
  headers: { 'Accept': 'application/json' },
  body: formData
})
  .then(res => res.json())
  .then(data => {
    if (data.success) {
      alert('Success!');
    } else {
      // data.errors contains validation errors
      const errors = Object.values(data.errors).flat();
      alert('Errors: ' + errors.join(', '));
    }
  });

Parse Error Redirect URL

// On your error page
const urlParams = new URLSearchParams(window.location.search);
const errorsJson = urlParams.get('errors');

if (errorsJson) {
  const errors = JSON.parse(errorsJson);
  // Display errors: errors.email, errors.name, etc.
  for (const [field, messages] of Object.entries(errors)) {
    console.log(`${field}: ${messages.join(', ')}`);
  }
}

🔧 Field Types Reference

Type	Description	Example Use
text	General text input	Names, addresses
email	Email validation	Email addresses
number	Numeric values	Age, quantity
url	Website addresses	Personal websites
date	Date values	Birth date
datetime	Date and time	Event time
time	Time only	Appointment time
file	File uploads	Resume, documents
array	Multiple values	Checkboxes
honeypot	Bot trap	Spam protection

✅ Validation Rules Quick Reference

Text Fields

- Required: Yes/No
- Min Length: e.g., 2
- Max Length: e.g., 100
- Allowed: alphabets, numbers, dash, underscore, spaces
- Transform: lowercase / UPPERCASE

Email Fields

- Required: Yes/No
- Max Length: e.g., 255
- Format: Automatically validated

Number Fields

- Required: Yes/No
- Min Value: e.g., 0
- Max Value: e.g., 999

File Fields

- Required: Yes/No
- Max Size: e.g., 5120 (KB)
- Allowed Types: pdf, jpg, png, doc, docx

🚦 HTTP Response Codes

Code	Meaning	Description
200	Success	Submission accepted
302	Redirect	Success/error redirect
403	Forbidden	Domain not allowed or form disabled
422	Validation Error	Field validation failed
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error

📊 Response Formats

Success Response

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

Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name must be at least 2 characters."]
  }
}

Domain Not Allowed

{
  "success": false,
  "message": "Domain not allowed"
}

🔐 Security Checklist

• Add your domain to whitelist (remove * in production)
• Enable CAPTCHA if experiencing spam
• Add honeypot fields to forms
• Set up field validation rules
• Configure max file upload sizes
• Limit allowed file types
• Review spam submissions regularly
• Use HTTPS for your website
• Set appropriate team member roles
• Configure redirect URLs

🎨 CAPTCHA Customization Options

window.FiraformCaptchaConfig = {
  width: '400px',              // Default: '100%'
  height: '50px',              // Default: '50px'
  gap: '4px',                  // Default: '4px'
  primaryColor: '#4CAF50',     // Default: '#4CAF50'
  backgroundColor: '#f0f0f0',  // Default: '#f0f0f0'
  borderColor: '#e0e0e0',      // Default: '#e0e0e0'
  borderRadius: '25px',        // Default: '25px'
  handleColor: 'white',        // Default: 'white'
  handleIconColor: '#666',     // Default: '#666'
  labelText: 'Slide to verify' // Default: 'Slide to verify'
};

👥 Team Roles

Role	Permissions
Owner	Full control, can delete team
Admin	Manage settings, members, forms
Manager	Edit forms, view submissions
Member	Basic access, view forms

🔌 Webhook Payload Structure

{
  "form_id": "550e8400-e29b-41d4-a716-446655440000",
  "form_name": "Contact Form",
  "submission_id": "123456",
  "submitted_at": "2026-01-21T14:30:00Z",
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "files": [
    {
      "field": "resume",
      "filename": "resume.pdf",
      "url": "https://files.firaform.com/...",
      "size": 245760
    }
  ],
  "metadata": {
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "referer": "https://yoursite.com/contact"
  }
}

📝 Domain Format Examples

✅ VALID:
- example.com
- www.example.com
- subdomain.example.com
- *.example.com (wildcard)
- localhost
- * (all domains)

❌ INVALID:
- https://example.com (no protocol)
- example.com/path (no paths)
- example.com:3000 (no ports)

💡 Common Validation Errors

"The email field is required."
"The email must be a valid email address."
"The name must be at least 2 characters."
"The name may not be greater than 100 characters."
"The age must be at least 18."
"The file must not be greater than 5120 kilobytes."
"The file must be a file of type: pdf, jpg, png."
"The CAPTCHA verification failed."

🚀 Rate Limits

Per Form:  100 submissions/minute
Per IP:    10 submissions/minute/form

📞 curl Examples

Basic Submission

curl -X POST "https://a.firaform.com/api/f/YOUR-FORM-ID" \
  -H "Accept: application/json" \
  -F "name=John Doe" \
  -F "email=john@example.com"

JSON Submission

curl -X POST "https://a.firaform.com/api/f/YOUR-FORM-ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

File Upload

curl -X POST "https://a.firaform.com/api/f/YOUR-FORM-ID" \
  -H "Accept: application/json" \
  -F "name=John Doe" \
  -F "resume=@/path/to/file.pdf"

🔍 Troubleshooting Quick Fixes

Problem	Solution
Form not accepting submissions	Check domain whitelist
Validation errors	Review field configuration
Not receiving emails	Verify team members, check spam folder
Files not uploading	Check file size/type limits
CAPTCHA not showing	Verify script URL includes form ID
Getting 403 error	Check domain whitelist, form status
Getting 429 error	Reduce submission rate

📚 Related Documentation

• Quick Start
• API Reference
• Field Configuration
• Form Settings
• Integrations

---

Last Updated: January 2026