---
title: "Add forms to Flask"
description: "Add a form backend to your Flask application. Forminit handles submissions, validation, file uploads, and notifications."
url: https://forminit.com/docs/flask/
---

# Add forms to Flask

Learn how to handle form submissions in Flask using the Forminit Python SDK.

---

## Prerequisites

1. **Create a Forminit account** at [forminit.com](https://forminit.com)
2. **Create a form** in your dashboard
3. **Set authentication mode to Protected** in Form Settings
4. **Create an API token** from **Account → API Tokens**

---

## 1. Install Dependencies

```bash
pip install forminit flask python-dotenv
```

## 2. Set Authentication Mode to Protected

Set authentication to Protected for server-side integrations. This enables higher rate limits and requires the `x-api-key` header.

<img src="/docs/auth-mode-protected.png" alt="Forminit Authentication Mode Protected" style="width: 450px;" />

## 3. Create an API Token and Add to Environment

Generate your secret API token from **Account → API Tokens** in the Forminit dashboard.

```bash
# .env
FORMINIT_API_KEY="fi_your_secret_api_key"
```

> **Caution**
>
> Never commit API keys to version control. Add `.env` to your `.gitignore` file.

## 4. Project Structure

```
my-flask-app/
├── app.py
├── .env
└── templates/
    └── contact.html
```

## 5. Create the Flask App

Forminit uses a block-based system to structure form data. Each submission contains an array of blocks representing different field types.

For complete documentation on all available blocks, field naming conventions, and validation rules, see the [Form Blocks Reference](https://forminit.com/docs/form-blocks/).

```python
# app.py
import os
from flask import Flask, request, jsonify, render_template
from forminit import ForminitClient
from dotenv import load_dotenv

load_dotenv()

app = Flask(__name__)
FORM_ID = "YOUR_FORM_ID"

@app.route("/")
def index():
    return render_template("contact.html")

@app.route("/submit", methods=["POST"])
def submit():
    client = ForminitClient(api_key=os.environ["FORMINIT_API_KEY"])

    # Pass user info for geolocation and attribution tracking
    client.set_user_info(
        ip=request.headers.get("X-Forwarded-For", request.remote_addr),
        user_agent=request.headers.get("User-Agent"),
        referer=request.headers.get("Referer"),
    )

    # Submit flat form data from HTML form
    form_data = request.form.to_dict()
    response = client.submit(FORM_ID, form_data)
    client.close()

    if response.get("error"):
        return jsonify({"success": False, "message": response["error"]["message"]}), 400

    return jsonify({"success": True, "submissionId": response["data"]["hashId"]})

if __name__ == "__main__":
    app.run(debug=True)
```

## 6. Create the HTML Template

```html
<!-- templates/contact.html -->
<form action="/submit" method="POST">
  <input type="text" name="fi-sender-fullName" placeholder="Name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  <input type="tel" name="fi-sender-phone" placeholder="Phone" />
  <textarea name="fi-text-message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>
```

**Field Naming Patterns:**

| Block Type | Pattern | Example |
|------------|---------|---------|
| Sender properties | `fi-sender-{property}` | `fi-sender-email` |
| Field blocks | `fi-{type}-{name}` | `fi-text-message` |

## 7. Run

```bash
flask run
```

---

## JSON Submission with Structured Blocks

For more control over the request payload, use JSON format with structured blocks:

```python
@app.route("/api/direct-submit", methods=["POST"])
def direct_submit():
    client = ForminitClient(api_key=os.environ["FORMINIT_API_KEY"])

    client.set_user_info(
        ip=request.headers.get("X-Forwarded-For", request.remote_addr),
        user_agent=request.headers.get("User-Agent"),
        referer=request.headers.get("Referer"),
    )

    payload = request.get_json()
    response = client.submit(FORM_ID, {
        "blocks": [
            {
                "type": "sender",
                "properties": {
                    "email": payload.get("email"),
                    "firstName": payload.get("firstName"),
                    "lastName": payload.get("lastName"),
                },
            },
            {
                "type": "text",
                "name": "message",
                "value": payload.get("message"),
            },
            {
                "type": "select",
                "name": "plan",
                "value": payload.get("plan"),
            },
        ],
    })
    client.close()

    if response.get("error"):
        return jsonify({"success": False, "message": response["error"]["message"]}), 400

    return jsonify({"success": True, "submissionId": response["data"]["hashId"]})
```

> **Caution**
>
> JSON submissions do not support file uploads. Use flat form data for forms with file fields.

---

## With Tracking Parameters

Pass UTM parameters and ad click IDs via the `tracking` argument:

```python
@app.route("/submit", methods=["POST"])
def submit():
    client = ForminitClient(api_key=os.environ["FORMINIT_API_KEY"])

    client.set_user_info(
        ip=request.headers.get("X-Forwarded-For", request.remote_addr),
        user_agent=request.headers.get("User-Agent"),
        referer=request.headers.get("Referer"),
    )

    form_data = request.form.to_dict()

    # Extract tracking parameters from query string
    tracking = {}
    for param in ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "gclid", "fbclid"]:
        value = request.args.get(param)
        if value:
            tracking[param] = value

    response = client.submit(FORM_ID, form_data, tracking=tracking)
    client.close()

    if response.get("error"):
        return jsonify({"success": False, "message": response["error"]["message"]}), 400

    return jsonify({"success": True, "submissionId": response["data"]["hashId"]})
```

---

## Response Structure

### Success Response

```python
const { data, redirectUrl, error } = response

# data contains:
{
    "hashId": "7LMIBoYY74JOCp1k",
    "date": "2026-01-01 21:10:24",
    "blocks": {
        "sender": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "john@example.com"
        },
        "message": "Hello world"
    }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `data.hashId` | str | Unique submission identifier |
| `data.date` | str | Submission timestamp (YYYY-MM-DD HH:mm:ss) |
| `data.blocks` | dict | All submitted field values |
| `redirectUrl` | str | Thank you page URL |

### Error Response

```python
{
    "error": {
        "error": "FI_SCHEMA_FORMAT_EMAIL",
        "code": 400,
        "message": "Invalid email format"
    }
}
```

---

## Error Handling

```python
@app.route("/submit", methods=["POST"])
def submit():
    client = ForminitClient(api_key=os.environ["FORMINIT_API_KEY"])

    client.set_user_info(
        ip=request.headers.get("X-Forwarded-For", request.remote_addr),
        user_agent=request.headers.get("User-Agent"),
        referer=request.headers.get("Referer"),
    )

    form_data = request.form.to_dict()
    response = client.submit(FORM_ID, form_data)
    client.close()

    if response.get("error"):
        error = response["error"]
        error_code = error.get("error")

        if error_code == "FI_SCHEMA_FORMAT_EMAIL":
            return jsonify({"success": False, "field": "email", "message": "Invalid email address"}), 400
        elif error_code == "FI_RULES_PHONE_INVALID":
            return jsonify({"success": False, "field": "phone", "message": "Invalid phone number"}), 400
        elif error_code == "TOO_MANY_REQUESTS":
            return jsonify({"success": False, "message": "Please wait before submitting again"}), 429
        else:
            return jsonify({"success": False, "message": error.get("message")}), 400

    return jsonify({"success": True, "submissionId": response["data"]["hashId"]})
```

### Common Error Codes

| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| `FORM_NOT_FOUND` | 404 | Form ID doesn't exist or was deleted |
| `FORM_DISABLED` | 403 | Form is disabled by owner |
| `MISSING_API_KEY` | 401 | API key required but not provided |
| `EMPTY_SUBMISSION` | 400 | No fields with values submitted |
| `FI_SCHEMA_FORMAT_EMAIL` | 400 | Invalid email format |
| `FI_RULES_PHONE_INVALID` | 400 | Invalid phone number format |
| `FI_SCHEMA_RANGE_RATING` | 400 | Rating not between 1-5 |
| `FI_DATA_COUNTRY_INVALID` | 400 | Invalid country code |
| `TOO_MANY_REQUESTS` | 429 | Rate limit exceeded |

---

## Security Best Practices

1. **Store API keys in environment variables** — Never hardcode keys in source code
2. **Use `.gitignore`** — Exclude `.env` files from version control
3. **Validate input server-side** — Don't rely solely on client-side validation
4. **Use HTTPS** — Always use secure connections in production
5. **Call `set_user_info()`** — Pass the real user's IP, user agent, and referer for accurate tracking

---

## Related Documentation

- [Python SDK Reference](https://forminit.com/docs/python-sdk/) — Full API reference for the Python SDK
- [Python Introduction](https://forminit.com/docs/python/) — General Python setup and usage
- [Form Blocks Reference](https://forminit.com/docs/form-blocks/) — Complete reference for all block types
- [File Uploads](https://forminit.com/docs/file-upload/) — Detailed file upload guide
- [API Reference](https://forminit.com/docs/submit-form-api/) — Full REST API documentation