Skip to content

man fox-grove-forms

Documentation

Everything you need to put a form on your site, make it look right, and get submissions where they need to go.

Quick start

  1. Start a free trial and build a form from the Forms page.
  2. Open the form’s Embed tab and copy its snippet. It contains your form token.
  3. Paste the snippet where the form should appear on your page.
index.html
<div id="FGMFormWrapper" data-id="YOUR_FORM_TOKEN"></div>
<script defer src="https://cdn.foxgrove.media/forms@latest.min.js"></script>

The script finds the element with the ID FGMFormWrapper, loads your form into it, and handles validation messages, hCaptcha and submission for you. Load the script once per page. To show more than one form on a page, use a data-fgm-form attribute (with its own data-id) on each container instead of the FGMFormWrapper ID.

Styling your form

Forms are rendered as plain HTML with stable IDs and classes you can target from your own stylesheet:

  • #FGMFormWrapper — your container; the form is rendered inside it.
  • #FGMForm — the form element itself.
  • .fgm-field-wrapper — wraps each field’s label, input and error message.
  • #error-{field_name} — the validation message for a field.
  • #error-captcha, #error-form — captcha and form-wide messages.
  • #successMsg — where the success message appears.

In the form builder you can add your own CSS classes to the form, to each field and its wrapper, and to the submit and cancel buttons — handy for grids such as sm:grid sm:grid-cols-2 sm:gap-4.

The default markup uses Tailwind CSS utility classes, including a brand color scale (brand-500, brand-600, brand-900). If your site uses Tailwind, define those colors and make sure the classes are compiled into your CSS:

app.css
@theme {
    --color-brand-500: #d15a1f;
    --color-brand-600: #b14610;
    --color-brand-900: #381300;
}

/* Tailwind v4.1+: compile the classes the embedded form uses */
@source inline("rounded-md bg-brand-600 hover:bg-brand-500 outline-brand-900/20 focus:outline-brand-500 text-brand-600 focus:ring-brand-600");

Not using Tailwind? Style the IDs and classes above, or add your own classes in the form builder.

Field types

Every field has a label and a name. The name is the key you’ll see in emails, exports and the API, so keep it short and snake_cased (for example first_name).

Field Type key Notes
Text text Collects a value.
Email email Name it email to enable reply-to, auto-replies and Mailchimp.
Phone tel Collects a value.
Number number Collects a value.
URL url Collects a value.
Date date Collects a value.
Time time Collects a value.
Paragraph textarea Collects a value.
Dropdown select Choices come from the field’s options.
Single choice radio Radio buttons; visitors pick one of the field’s options.
Multiple choice checkboxes Checkboxes; visitors tick any number of the field’s options. Submitted as a list.
Checkbox checkbox A single checkbox that sends “Yes” (or the one value you set); when required, it must be ticked. Enter several values separated by commas to let visitors tick more than one.
US state state Dropdown of US states and DC.
File upload file Paid plans. Stored privately; size limit depends on your plan.
Hidden hidden Sends a fixed value you set on the field.
Submit button submit Replaces the default submit button.
Reset button reset Replaces the default cancel button.
Open group open-div Starts a wrapper element so you can group fields, e.g. in a grid.
Close group close-div Ends the most recent group.
Divider horizontal-rule A visual divider.

Mark a field as required and it will be checked both in the browser and on our servers. Email, number, URL and date fields are validated for their format automatically.

Spam protection

  • Honeypot. Every form includes a hidden field that people never see but bots fill in. Those submissions are quietly discarded.
  • hCaptcha. Turn on the captcha in a form’s settings and the widget is added automatically. Submissions without a valid captcha are rejected.
  • Rate limiting. Each visitor can send up to 10 submissions a minute to a form.
  • Allowed domains. List the domains your form lives on (subdomains are included) and submissions posted from anywhere else are refused.

After a submission

Choose what visitors see once their submission is accepted: a success message shown in place (in #successMsg), or a redirect to a page of your own, such as a thank-you page.

Each plan includes a number of submissions per month. If a team reaches its limit, its forms pause and visitors see a friendly message until the limit resets at the start of the next month, or until you upgrade.

Notifications & auto-replies

New submissions are emailed to the addresses you list on the form (or the team owner if you list none). When the form has a field named email, replying to the notification goes straight to the person who submitted it. A field named subject becomes the email’s subject line.

Auto-replies (paid plans) send a confirmation to the submitter. Use placeholders with any field name in the subject and body:

auto-reply.txt
Thanks, {{ first_name }}! We received your message and will reply to {{ email }} soon.

The body can be plain text or HTML. Auto-replies come from our sending address with your team or form name, and you can set a reply-to address so responses reach you.

File uploads

Add a File upload field to accept attachments on the Starter plan and above. The maximum size per file depends on your plan (Starter: 5 MB, Pro: 25 MB, Agency: 50 MB).

Files are kept in private storage. Download them from the dashboard, or from the links in notification emails, which expire after 30 days.

Mailchimp

On the Pro and Agency plans you can add submitters to a Mailchimp audience. Paste your Mailchimp API key under Team → Integrations, then enable Mailchimp on a form and enter the audience ID.

The form needs a field named email. First and last names are sent from fields named first_name and last_name, or split from a field named name. Choose double opt-in to have Mailchimp send its confirmation email first.

Submission responses

The embed script handles these for you, but if you’re building your own integration, submissions return JSON:

success.json
// 200 OK
{
    "success": true,
    "message": "Form Submitted Successfully!",
    "redirect": "https://example.com/thanks"
}
validation-error.json
// 400 Bad Request
{
    "success": false,
    "errors": {
        "email": ["The Email field must be a valid email address."]
    }
}
  • 400 — validation failed; errors are keyed by field name.
  • 401 — the captcha was missing or invalid (errors.captcha).
  • 403 — the submission came from a domain that isn’t allowed (errors.form).
  • 404 — the form doesn’t exist or is turned off.
  • 429 — too many submissions, or the monthly limit was reached (errors.form).

Using your own JavaScript

Prefer to write your own markup? Post the form’s fields as FormData to your form’s endpoint. Field names must match the names in the builder; leave the hidden _fgm_hp field out (or empty), and include h-captcha-response if the captcha is on.

form.js
const form = document.querySelector('#my-form');

form.addEventListener('submit', async (event) => {
    event.preventDefault();

    const response = await fetch('https://foxgrove.media/api/forms/YOUR_FORM_TOKEN', {
        method: 'POST',
        headers: { Accept: 'application/json' },
        body: new FormData(form),
    });

    const result = await response.json();

    if (result.success) {
        result.redirect ? location.assign(result.redirect) : form.reset();
    } else {
        console.log(result.errors);
    }
});

API

Create, update and delete forms and read stored submissions from your own code. The API is available on the Pro and Agency plans.

  • Base URL: https://foxgrove.media/api/v1
  • Authentication: create a token under Team → API tokens and send it as Authorization: Bearer YOUR_API_TOKEN with Accept: application/json.
  • Abilities: every token can read. Turn on “Allow creating, editing and deleting” when you create a token to give it write access, which create, update and delete need.
  • Team scope: a token belongs to one team and only sees that team’s forms and submissions.
  • Rate limit: 60 requests per minute per token.
  • OpenAPI spec: https://foxgrove.media/openapi.json — a machine-readable description of every endpoint, for code generators and AI agents.
Endpoint Ability What it does
GET /team read The team, its plan, plan limits (null = unlimited) and usage.
GET /field-types read Every field type a form can use.
GET /forms read List forms (paginated; per_page up to 100).
POST /forms write Create a form. Returns 201 with the form and its embed code.
GET /forms/{token} read One form with its settings, fields and embed code.
PATCH /forms/{token} write Update a form; send only what changes (PUT also works).
DELETE /forms/{token} write Move a form to the trash (204).
GET /forms/{token}/submissions read Newest first. Filters: since, until, search, unread, per_page, page.
GET /forms/{token}/submissions/{id} read One submission.
DELETE /forms/{token}/submissions/{id} write Move a submission to the trash (204).

Creating and updating forms

  • Create and update take the same keys a form response returns (name, description, redirect_url, notify_emails, auto_reply_subject and so on), so you can read a form, edit it and send it back.
  • name is required when creating. Without fields, a new form starts with name, email and message fields.
  • fields is the complete, ordered list of fields. On update it replaces all existing fields, so read the form first and send the whole edited list.
  • Each field has type, name, label, required, show_label, published, placeholder, options (for select, radio and checkboxes, and optionally checkbox), input_css and wrapper_css. Input fields need a unique name and a label.
  • Plan rules apply: auto-replies, Mailchimp and file fields need a plan that includes them, and creating a form beyond your plan’s limit returns 402.
create-form.sh
curl -X POST https://foxgrove.media/api/v1/forms \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Contact",
      "redirect_url": "https://example.com/thanks",
      "fields": [
        {"type": "open-div", "wrapper_css": "grid grid-cols-2 gap-4"},
        {"type": "text", "name": "first_name", "label": "First name", "required": true},
        {"type": "text", "name": "last_name", "label": "Last name"},
        {"type": "close-div"},
        {"type": "email", "name": "email", "label": "Email", "required": true},
        {"type": "textarea", "name": "message", "label": "Message", "required": true}
      ]
    }'

Reading submissions

terminal
curl "https://foxgrove.media/api/v1/forms/YOUR_FORM_TOKEN/submissions?since=2026-11-01" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json"
response.json
{
    "data": [
        {
            "id": 1042,
            "form_token": "YOUR_FORM_TOKEN",
            "values": {
                "name": "Avery Parker",
                "email": "avery@example.com",
                "message": "Hi! We'd love a quote."
            },
            "files": [],
            "read": false,
            "created_at": "2026-11-10T18:24:51+00:00"
        }
    ],
    "links": { "next": null },
    "meta": { "current_page": 1, "per_page": 50, "total": 1 }
}

values holds the submitted values keyed by field name. File URLs are temporary download links that expire after 30 minutes. Deleting moves forms and submissions to the trash, where they can be restored from the dashboard.

Errors

  • 401 — missing or invalid token.
  • 402 — the plan doesn’t include API access, or creating a form would exceed the plan’s limit (code: plan_limit_reached).
  • 403 — the token lacks the read or write ability, or isn’t linked to a team you belong to.
  • 404 — no form or submission with that identifier belongs to the token’s team.
  • 422 — validation failed; errors are keyed by payload field, such as fields.2.name.
  • 429 — rate limited.

AI agents (MCP)

The Model Context Protocol (MCP) lets AI assistants such as Claude use outside services as tools. Connect one to Fox Grove Forms and it can build forms, hand you embed codes and read submissions for you.

  1. Create a token under Team → API tokens. Turn on write access if the agent should create, change or delete forms.
  2. Point your MCP client at https://foxgrove.media/mcp and send the token as a Bearer token.

Claude Code:

terminal
claude mcp add --transport http foxgrove-forms https://foxgrove.media/mcp --header "Authorization: Bearer YOUR_API_TOKEN"

Other MCP clients:

mcp.json
{
  "mcpServers": {
    "foxgrove-forms": {
      "type": "http",
      "url": "https://foxgrove.media/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Available tools:

  • get_team — the team’s plan, limits and usage.
  • list_forms — the team’s forms with tokens, status and embed codes.
  • get_form — one form with its settings, fields and embed code.
  • create_form — create a form, optionally with fields and settings.
  • update_form — change settings and/or fields (sending fields replaces them all).
  • delete_form — move a form to the trash.
  • list_submissions — a form’s submissions, with date, search and unread filters.
  • get_submission — one submission, with expiring file links.
  • delete_submission — move a submission to the trash.

The agent works with the same team, abilities, plan rules and rate limit as the REST API. delete_form and delete_submission move items to the trash rather than deleting them for good, and agents are asked to confirm with you first.

For AI agents & LLMs

Everything on this page is also available in formats that are easy for language models to read:

  • llms.txt — a short guide to the site with links.
  • llms-full.txt — the full documentation in one Markdown file.
  • docs.md — this page as Markdown. Requests that prefer text/markdown get it automatically.
  • openapi.json — the REST API as an OpenAPI 3.1 spec.