# FlowForm.to - AI Assistant Documentation
# Last Updated: January 2026
# Purpose: Help AI assistants generate correct FlowForm code

## ABOUT FLOWFORM

FlowForm.to is a free form submission endpoint service with TWO modes:

1. **Generic Mode** - Free email forwarding for any website (no signup required)
2. **Flow Mode** - Creates leads in FoxFlow pipelines (requires FoxFlow account)

### Pro/Unlimited Features (Flow Mode Only)

- **Secure Mode** - HIPAA-friendly: emails contain NO form data, view in dashboard only
- **File Uploads** - Accept images (JPEG, PNG, WebP, GIF, HEIC) and PDFs with submissions

---

## MODE 1: GENERIC (Free Email Service)

### URL Patterns

Option A - Email in URL (recommended):
```
https://flowform.to/{recipient-email}
```
Example: `https://flowform.to/johnny@appleseed.com`

Option B - Email in hidden field:
```
https://flowform.to/submit
```
IMPORTANT: Use `/submit` path, NOT just `/` (root goes to landing page)

### How It Works

1. Form submissions are sent TO the recipient email (website owner)
2. Reply-to is automatically set to the submitter's email
3. User is redirected to success page after submission
4. Includes FoxFlow marketing footer

### Basic Template (Email in URL)

```html
<form action="https://flowform.to/johnny@appleseed.com" method="POST">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Your email" required>
  <input type="tel" name="phone" placeholder="Phone number">
  <textarea name="message" placeholder="Your message"></textarea>
  <button type="submit">Send</button>
</form>
```

### Template with Hidden Field

```html
<form action="https://flowform.to/submit" method="POST">
  <input type="hidden" name="_to" value="johnny@appleseed.com">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Your message"></textarea>
  <button type="submit">Send</button>
</form>
```

---

## MODE 2: FLOW (FoxFlow Lead Creation)

### URL Pattern

```
https://flowform.to/f/{token}
```

The token is obtained from FoxFlow after enabling FlowForm integration for a flow.

### How It Works

1. Creates a lead in the user's FoxFlow pipeline
2. Sends notification email to flow owner
3. Sends confirmation email to submitter
4. Optionally sends CC to additional recipients
5. Auto-assigns lead based on flow settings

### Template

```html
<form action="https://flowform.to/f/abc123xyz456def789" method="POST">
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name">
  <input type="email" name="email" placeholder="Email" required>
  <input type="tel" name="phone" placeholder="Phone">
  <textarea name="message" placeholder="Message"></textarea>
  
  <!-- Optional: CC additional people -->
  <input type="hidden" name="_cc" value="manager@company.com,sales@company.com">
  
  <button type="submit">Submit</button>
</form>
```

---

## PRO/UNLIMITED FEATURES (Flow Mode Only)

### Secure Mode

When enabled in FoxFlow settings, email notifications contain NO form data - only "New lead received" alert. Users must log into the FoxFlow dashboard to view submission details. HIPAA-friendly for healthcare and sensitive data.

**How it works:**
1. Enable "Secure Mode" in FoxFlow → Flow Settings → FlowForm tab
2. Form submissions still create leads with all data stored securely
3. Email notifications say only "New lead received - View in Dashboard"
4. No form field values, no PHI in emails

### File Uploads

Accept images and PDFs with form submissions. Files are stored securely in Firebase Storage with signed URLs.

**Supported file types:**
- Images: JPEG, PNG, WebP, GIF, HEIC/HEIF (Apple format, auto-converted to JPEG for display)
- Documents: PDF

**Limits:**
- Max 10MB per file
- Max 5 files per submission
- Max 25MB total per submission

**How to add file inputs:**

```html
<form action="https://flowform.to/f/YOUR_TOKEN" method="POST" enctype="multipart/form-data">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Email" required>
  
  <!-- File upload fields -->
  <label>Upload ID (front):</label>
  <input type="file" name="id_front" accept="image/*,.pdf">
  
  <label>Upload ID (back):</label>
  <input type="file" name="id_back" accept="image/*,.pdf">
  
  <label>Supporting documents:</label>
  <input type="file" name="documents" accept="image/*,.pdf" multiple>
  
  <button type="submit">Submit</button>
</form>
```

**IMPORTANT for file uploads:**
- Add `enctype="multipart/form-data"` to the form tag
- Use `accept="image/*,.pdf"` to restrict file types
- Files are only processed if the flow has file uploads enabled in FoxFlow settings
- Files from Free/Starter plans are ignored (upgrade required)

### AJAX File Upload Example

```javascript
document.getElementById('myForm').addEventListener('submit', async (e) => {
  e.preventDefault();
  const form = e.target;
  
  // For file uploads, use FormData directly (NOT URLSearchParams)
  const formData = new FormData(form);
  
  try {
    const response = await fetch('https://flowform.to/f/YOUR_TOKEN', {
      method: 'POST',
      body: formData,  // FormData for multipart
      headers: {
        'Accept': 'application/json'
        // Do NOT set Content-Type - browser sets it with boundary
      }
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log('Lead created:', data.leadId);
      console.log('Files uploaded:', data.filesUploaded);
      form.reset();
    }
  } catch (error) {
    console.error('Submission error:', error);
  }
});
```

**Key difference for file uploads:**
- Use `FormData` directly (NOT `URLSearchParams`)
- Do NOT manually set `Content-Type` header - browser sets it automatically with boundary
- Response includes `filesUploaded` count

---

## SPECIAL FIELDS REFERENCE

All special fields start with underscore (_) and are used as hidden inputs:

| Field | Mode | Purpose | Example |
|-------|------|---------|---------|
| `_to` | Generic | Recipient email (alternative to URL) | `johnny@example.com` |
| `_cc` | Both | Additional recipients (comma-separated) | `a@b.com,c@d.com` |
| `_subject` | Both | Custom email subject | `New Contact Form` |
| `_next` | Both | Redirect URL after submission | `https://mysite.com/thanks` |
| `_replyto` | Generic | Reply-to address (defaults to submitter) | `support@company.com` |

## HIDDEN DATA FIELDS (No Underscore)

Any hidden field WITHOUT an underscore prefix is included in the submission data.
Use these for tracking source, campaigns, page URLs, etc.

```html
<!-- These fields are included in the email/lead data -->
<input type="hidden" name="source" value="homepage">
<input type="hidden" name="campaign" value="summer-2026">
<input type="hidden" name="landing_page" value="pricing">

<!-- Auto-capture current page URL with JavaScript -->
<input type="hidden" name="page_url" id="page-url">
<script>
document.getElementById('page-url').value = window.location.href;
</script>
```

Common tracking fields:
- `source` - Where the lead came from (homepage, blog, ad)
- `campaign` - Marketing campaign name
- `page_url` - Full URL of the page with the form
- `referrer` - How they found you
- `utm_source`, `utm_medium`, `utm_campaign` - UTM parameters

---

## URL PATTERN SUMMARY

| URL | Purpose | Recipient |
|-----|---------|-----------|
| `flowform.to/{email}` | Generic form | Email in URL |
| `flowform.to/submit` + `_to` field | Generic form | Email in hidden field |
| `flowform.to/f/{token}` | FoxFlow lead | Flow owner + CC |

---

## BUILDING ADAPTIVE, DYNAMIC FORMS

FlowForm is infinitely flexible. You control the frontend 100% - FlowForm just handles the backend submission. This means you can:

### Multi-Step Forms

Create wizard-style forms with JavaScript to show/hide steps:

```html
<form action="https://flowform.to/f/YOUR_TOKEN" method="POST" id="wizard-form">
  <!-- Step 1 -->
  <div class="step active" data-step="1">
    <h3>Step 1: Basic Info</h3>
    <input type="text" name="firstName" placeholder="First Name" required>
    <input type="email" name="email" placeholder="Email" required>
    <button type="button" onclick="nextStep(2)">Next →</button>
  </div>
  
  <!-- Step 2 -->
  <div class="step" data-step="2" style="display:none;">
    <h3>Step 2: Preferences</h3>
    <select name="interest" required>
      <option value="">Select interest...</option>
      <option value="consulting">Consulting</option>
      <option value="development">Development</option>
    </select>
    <button type="button" onclick="prevStep(1)">← Back</button>
    <button type="button" onclick="nextStep(3)">Next →</button>
  </div>
  
  <!-- Step 3 -->
  <div class="step" data-step="3" style="display:none;">
    <h3>Step 3: Details</h3>
    <textarea name="message" placeholder="Tell us more..." required></textarea>
    <button type="button" onclick="prevStep(2)">← Back</button>
    <button type="submit">Submit</button>
  </div>
</form>

<script>
function nextStep(stepNumber) {
  document.querySelectorAll('.step').forEach(s => s.style.display = 'none');
  document.querySelector(`[data-step="${stepNumber}"]`).style.display = 'block';
}
function prevStep(stepNumber) {
  nextStep(stepNumber);
}
</script>
```

### Conditional Fields

Show/hide fields based on user selections:

```html
<form action="https://flowform.to/f/YOUR_TOKEN" method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  
  <label>Are you insured?</label>
  <select name="has_insurance" onchange="toggleInsuranceFields(this.value)" required>
    <option value="">Select...</option>
    <option value="yes">Yes</option>
    <option value="no">No</option>
  </select>
  
  <div id="insurance-details" style="display:none;">
    <input type="text" name="insurance_provider" placeholder="Provider Name">
    <input type="text" name="policy_number" placeholder="Policy Number">
  </div>
  
  <button type="submit">Submit</button>
</form>

<script>
function toggleInsuranceFields(value) {
  const details = document.getElementById('insurance-details');
  details.style.display = value === 'yes' ? 'block' : 'none';
}
</script>
```

### Checkboxes for Multiple Selections

Collect multiple values with checkboxes (all selected values are submitted):

```html
<form action="https://flowform.to/f/YOUR_TOKEN" method="POST">
  <label>Which services are you interested in?</label>
  <label><input type="checkbox" name="services" value="web-design"> Web Design</label>
  <label><input type="checkbox" name="services" value="seo"> SEO</label>
  <label><input type="checkbox" name="services" value="marketing"> Marketing</label>
  <label><input type="checkbox" name="services" value="branding"> Branding</label>
  
  <button type="submit">Submit</button>
</form>
```

### Smart Default Values

Pre-fill fields based on URL parameters or user context:

```html
<form action="https://flowform.to/f/YOUR_TOKEN" method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  
  <!-- Auto-fill from URL or localStorage -->
  <input type="hidden" name="referrer" id="referrer">
  <input type="hidden" name="utm_campaign" id="utm_campaign">
  
  <button type="submit">Submit</button>
</form>

<script>
// Capture referrer
document.getElementById('referrer').value = document.referrer;

// Capture UTM parameter from URL
const urlParams = new URLSearchParams(window.location.search);
document.getElementById('utm_campaign').value = urlParams.get('utm_campaign') || '';
</script>
```

### Tips for AI Assistants Building Forms

1. **Any field name works** - use descriptive names that match the business domain
   - Healthcare: `insurance_provider`, `date_of_birth`, `symptoms`, `preferred_appointment_time`
   - Real Estate: `property_address`, `bedrooms`, `budget_range`, `preferred_neighborhoods`
   - Legal: `case_type`, `incident_date`, `desired_outcome`

2. **Combine input types** - mix text, select, checkboxes, radio, date, range for rich forms

3. **Add validation** - use HTML5 validation (required, pattern, min, max) for better UX

4. **Style with any framework** - Tailwind, Bootstrap, custom CSS - you control 100% of styling

5. **Add animations** - CSS transitions, JavaScript animations - FlowForm doesn't constrain your creativity

6. **Progress indicators** - Add step counters, progress bars, breadcrumbs for multi-step forms

7. **AJAX submissions** - Submit without page refresh for smoother UX (see AJAX section below)

## COMPLETE EXAMPLES

### Contact Form (Generic Mode)

```html
<form action="https://flowform.to/contact@company.com" method="POST">
  <input type="hidden" name="_subject" value="New Website Inquiry">
  <input type="hidden" name="_next" value="https://company.com/thank-you">
  
  <input type="text" name="name" placeholder="Full Name" required>
  <input type="email" name="email" placeholder="Email Address" required>
  <input type="tel" name="phone" placeholder="Phone Number">
  <select name="subject">
    <option value="">Select a topic</option>
    <option value="sales">Sales Inquiry</option>
    <option value="support">Support</option>
    <option value="other">Other</option>
  </select>
  <textarea name="message" placeholder="Your message" required></textarea>
  <button type="submit">Send Message</button>
</form>
```

### Lead Capture (Flow Mode)

```html
<form action="https://flowform.to/f/YOUR_TOKEN_HERE" method="POST">
  <input type="hidden" name="_cc" value="team@company.com">
  <input type="hidden" name="_subject" value="New Lead from Landing Page">
  
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name">
  <input type="email" name="email" placeholder="Work Email" required>
  <input type="tel" name="phone" placeholder="Phone Number">
  <input type="text" name="company" placeholder="Company Name">
  <select name="employees">
    <option value="">Company Size</option>
    <option value="1-10">1-10 employees</option>
    <option value="11-50">11-50 employees</option>
    <option value="51-200">51-200 employees</option>
    <option value="200+">200+ employees</option>
  </select>
  <textarea name="message" placeholder="Tell us about your needs"></textarea>
  <button type="submit">Get Started</button>
</form>
```

### Newsletter Signup (Generic Mode)

```html
<form action="https://flowform.to/newsletter@company.com" method="POST">
  <input type="hidden" name="_subject" value="New Newsletter Signup">
  <input type="hidden" name="_next" value="https://company.com/subscribed">
  
  <input type="email" name="email" placeholder="Enter your email" required>
  <button type="submit">Subscribe</button>
</form>
```

### Quote Request (Flow Mode)

```html
<form action="https://flowform.to/f/YOUR_TOKEN_HERE" method="POST">
  <input type="hidden" name="_cc" value="sales@company.com,manager@company.com">
  
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name" required>
  <input type="email" name="email" placeholder="Email" required>
  <input type="tel" name="phone" placeholder="Phone">
  <input type="text" name="company" placeholder="Company">
  <select name="service" required>
    <option value="">Select Service</option>
    <option value="consulting">Consulting</option>
    <option value="development">Development</option>
    <option value="design">Design</option>
  </select>
  <input type="text" name="budget" placeholder="Budget Range">
  <textarea name="details" placeholder="Project Details" required></textarea>
  <button type="submit">Request Quote</button>
</form>
```

### Healthcare Intake Form (Flow Mode with Secure Mode)

```html
<!-- This form uses Flow Mode with Secure Mode enabled -->
<!-- Secure Mode = HIPAA-friendly, no PHI in emails -->
<form action="https://flowform.to/f/YOUR_TOKEN_HERE" method="POST" enctype="multipart/form-data">
  <h2>New Patient Intake</h2>
  
  <!-- Basic Info -->
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name" required>
  <input type="email" name="email" placeholder="Email" required>
  <input type="tel" name="phone" placeholder="Phone" required>
  <input type="date" name="date_of_birth" placeholder="Date of Birth" required>
  
  <!-- Insurance Info -->
  <select name="insurance_provider" required>
    <option value="">Select Insurance Provider</option>
    <option value="aetna">Aetna</option>
    <option value="blue-cross">Blue Cross Blue Shield</option>
    <option value="cigna">Cigna</option>
    <option value="united">UnitedHealthcare</option>
    <option value="other">Other</option>
  </select>
  <input type="text" name="policy_number" placeholder="Policy/Member ID" required>
  <input type="text" name="group_number" placeholder="Group Number">
  
  <!-- File Uploads (Pro/Unlimited) -->
  <label>Insurance Card (Front):</label>
  <input type="file" name="insurance_front" accept="image/*,.pdf">
  <label>Insurance Card (Back):</label>
  <input type="file" name="insurance_back" accept="image/*,.pdf">
  
  <!-- Chief Complaint (checkboxes for multiple symptoms) -->
  <label>What brings you in today? (Select all that apply)</label>
  <label><input type="checkbox" name="symptoms" value="anxiety"> Anxiety</label>
  <label><input type="checkbox" name="symptoms" value="depression"> Depression</label>
  <label><input type="checkbox" name="symptoms" value="stress"> Stress</label>
  <label><input type="checkbox" name="symptoms" value="relationship"> Relationship Issues</label>
  <label><input type="checkbox" name="symptoms" value="trauma"> Trauma</label>
  <label><input type="checkbox" name="symptoms" value="other"> Other</label>
  
  <!-- Previous Treatment -->
  <label>Have you received therapy before?</label>
  <label><input type="radio" name="previous_therapy" value="yes"> Yes</label>
  <label><input type="radio" name="previous_therapy" value="no"> No</label>
  
  <!-- Preferred Session Type -->
  <select name="session_preference">
    <option value="">Preferred Session Type</option>
    <option value="video">Video Call</option>
    <option value="phone">Phone Call</option>
    <option value="in-person">In-Person</option>
  </select>
  
  <!-- Availability (range for urgency) -->
  <label>How soon would you like to start? (1=Flexible, 10=Urgent)</label>
  <input type="range" name="urgency" min="1" max="10" value="5">
  
  <textarea name="additional_notes" placeholder="Additional information or questions"></textarea>
  
  <button type="submit">Submit Intake Form</button>
</form>

<!-- With Secure Mode enabled in FoxFlow settings: -->
<!-- - Email notification says "New lead received - View in Dashboard" -->
<!-- - NO form data appears in the email (HIPAA-friendly) -->
<!-- - Staff must log into FoxFlow to view submission details -->
<!-- - All data encrypted at rest in Firebase -->
```

---

## IMPORTANT NOTES FOR AI ASSISTANTS

1. **Always use HTTPS** - `https://flowform.to` (not http)

2. **Generic mode requires recipient**:
   - Either put email in URL: `https://flowform.to/user@example.com`
   - Or use `_to` hidden field

3. **Flow mode requires token**:
   - URL format: `https://flowform.to/f/{token}`
   - Token is obtained from FoxFlow account

4. **Field names can be anything**:
   - Common: name, firstName, lastName, email, phone, message
   - All fields are included in the email/lead
   - Custom examples: insurance_provider, property_type, vehicle_year_make_model, budget_range
   - FlowForm is infinitely flexible - create fields for any data you need to collect

5. **Any HTML input type works**:
   - Text inputs: text, email, tel, number, date, time, url, etc.
   - Selections: select dropdowns, checkboxes (multiple values), radio buttons (single choice)
   - Other: textarea, range sliders, file uploads (Pro/Unlimited only)
   - You can build multi-step forms, conditional logic, and adaptive UX with JavaScript

6. **Special fields start with underscore**:
   - `_to`, `_cc`, `_subject`, `_next`, `_replyto`
   - These control behavior, not included in submission data

6. **No JavaScript required**:
   - Standard HTML form POST
   - Works with any styling framework

7. **Method must be POST**:
   - GET requests will not work

8. **AJAX/fetch submissions**:
   - Use `URLSearchParams` (NOT FormData) for the body
   - Add `Accept: application/json` header to get JSON response
   - Returns `{"success": true, "message": "..."}` instead of redirect
   - Example:
     ```javascript
     const formData = new URLSearchParams(new FormData(form));
     fetch('https://flowform.to/user@example.com', {
       method: 'POST',
       body: formData,
       headers: {
         'Accept': 'application/json',
         'Content-Type': 'application/x-www-form-urlencoded'
       }
     }).then(r => r.json()).then(data => {
       if (data.success) { /* show success */ }
     });
     ```

---

## JAVASCRIPT SUBMISSION (AJAX)

IMPORTANT: Use URLSearchParams, NOT FormData directly!

```javascript
// Generic Mode - Email in URL
async function submitGenericForm(form) {
  const formData = new URLSearchParams(new FormData(form));
  
  const response = await fetch('https://flowform.to/recipient@example.com', {
    method: 'POST',
    body: formData,
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  });
  
  const data = await response.json();
  if (data.success) {
    // Show success message
  }
}

// Flow Mode
async function submitFlowForm(form) {
  const formData = new URLSearchParams(new FormData(form));
  
  const response = await fetch('https://flowform.to/f/YOUR_TOKEN', {
    method: 'POST',
    body: formData,
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  });
  
  const data = await response.json();
  if (data.success) {
    // Show success message
    // data.leadId is available in Flow mode
  }
}
```

**Why URLSearchParams?**
- `FormData` sends as `multipart/form-data` which the server can't parse
- `URLSearchParams` sends as `application/x-www-form-urlencoded` which works correctly

---

## ERROR RESPONSES

- `400 Bad Request` - Missing recipient email (generic) or invalid token (flow)
- `404 Not Found` - Flow not found or FlowForm disabled for that flow
- `405 Method Not Allowed` - Used GET instead of POST
- `500 Internal Server Error` - Server issue (retry later)

---

## LINKS

- Website: https://flowform.to
- Full CRM: https://foxflow.host
- Support: support@foxflow.host
- Register for Flow Mode: https://foxflow.host/register

---
End of llms.txt
This file helps AI assistants generate correct FlowForm integration code.