Creating forms

There are three ways to start a new form. The new form screen in the dashboard offers all three, and the REST API and MCP server can do the same.

Whichever way you start, the form is saved through the same action and checked against the same schema rules, so a form made one way can be edited any other way.

A new form is published as soon as it is created, unless you pass draft: true. Then it starts unpublished and takes sandbox submissions only until you publish it. See create an unpublished form.

Start from a template

Templates are ready-made drafts: a name, a description for the spam filter, a schema and settings. Some also turn on the autoresponder or add a smart rule.

Create a form from a template

Pass "template": "<key>" when you create a form. The template’s fields and settings are used, and anything else you pass overrides them, so name and schema become optional. An unknown key is a 422 on template.

The example below uses illustrative values.

curl -X POST https://YOUR-QUICKFORMS-HOST/api/v1/forms \
  -H "Authorization: Bearer $QUICKFORMS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"template": "event-rsvp", "name": "Summer party RSVP", "mode": "sandbox"}'

{
  "tool": "create-form",
  "arguments": { "template": "event-rsvp", "name": "Summer party RSVP", "mode": "sandbox" }
}

The response is the created form, the same as any POST /api/v1/forms.

List the templates

GET /api/v1/form-templates returns every template with its key, name, summary, category, fields (the field labels) and the full draft. The MCP tool list-form-templates returns the same list without the draft. See the API reference for an example response.

Describe it to the AI form builder

Describe the form in plain English, for example “a quote request form for a garden landscaping business”, and the AI form builder returns a draft. The draft has:

• A name and a schema of fields.
• A description, which the spam filter reads as context.
• Up to 3 smart rules for the spam filter.
• A success message.
• An autoresponder, turned on or off, with a subject and body.

Nothing is saved until you say so. In the dashboard the draft opens in the editor. Through the API and MCP you get the draft back, or pass save: true to create the form in one step.

What happens to the model’s answer

The builder asks an OpenAI model for a form in a fixed structure, then cleans the answer before you see it:

• Fields with a type quickforms doesn’t support are dropped.
• Field names are made safe (lowercase letters, numbers and underscores) and unique within the form.
• Choice fields (select, radio, checkboxes) with no options are dropped.
• Only the field keys that matter for each type are kept, and min and max are dropped from date fields.
• The result is validated like any other schema.

Generate a draft

The example prompt and draft below are illustrative. The model’s answer varies from request to request.

curl -X POST https://YOUR-QUICKFORMS-HOST/api/v1/forms/generate \
  -H "Authorization: Bearer $QUICKFORMS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A quote request form for a garden landscaping business", "save": false}'

{
  "tool": "generate-form",
  "arguments": { "prompt": "A quote request form for a garden landscaping business", "save": false }
}

{
  "data": {
    "draft": {
      "name": "Landscaping quote",
      "description": "Homeowners asking for a quote for garden landscaping work.",
      "schema": {
        "fields": [
          { "name": "name", "type": "text", "label": "Name", "required": true },
          { "name": "email", "type": "email", "label": "Email", "required": true },
          { "name": "postcode", "type": "text", "label": "Postcode", "required": true },
          { "name": "work", "type": "checkboxes", "label": "What work do you need?", "required": true, "options": ["Design", "Planting", "Paving", "Fencing"] },
          { "name": "details", "type": "textarea", "label": "Tell us about your garden", "required": false }
        ]
      },
      "settings": {
        "success_message": "Thanks, we will be in touch about your quote.",
        "autoresponder": { "enabled": true, "subject": "Thanks {{name}}, we got your quote request", "body": "..." },
        "spam": { "rules": ["Must be a request for garden landscaping work"] }
      }
    }
  }
}

The draft is in the same shape POST /api/v1/forms and create-form accept, so you can edit it and send it straight back to create the form. With save: true the response is the created form with status 201, the same as POST /api/v1/forms.

Errors and limits

Generating is rate limited to 30 forms an hour per user by default (QUICKFORMS_FORM_BUILDER_PER_HOUR). The MCP tool returns an error saying to try again later instead of a 429.

Configuration

The builder uses laravel/ai with the OpenAI provider.

Start empty

Create a form with a name and your own schema. See the schema reference for every field type and option, and POST /api/v1/forms for a full example.