> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-added forms

> Configure rules that automatically add the right forms to a quote

Most quotes need the same handful of forms attached every time, and which forms
they need usually depends on the quote's answers. **Auto-added forms** let you
capture that as configuration instead of relying on people to remember: you write
a small set of rules — one per form — and AI Insurance adds the matching forms to
the quote for you, in the order you choose.

A rule is just three things:

| Part          | What it does                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Form**      | Which form the rule is about (an uploaded form template, by its `FM-XXXX` form number — e.g. `FM-0001`).                              |
| **Rank**      | The order forms are added — lower ranks first. Ranks must be unique across all rules.                                                 |
| **Condition** | When to add the form. A Jexl expression over the quote's field values — the same expression model as display and required conditions. |

Rules are part of your company configuration, alongside your fields, pages, and
option sets. To add or change one, **contact your AI Insurance team** — tell them
which form, when it should be added, and where it belongs in the order. Once the
configuration is applied, the rules run automatically during the quote flow.

<Note>
  Auto-added forms apply to the **quote flow**. Rules may reference **Quote**
  forms and **Policy** forms (the two form categories used in quoting) — both are
  added to the quote as it is built. Claim/Incident forms are attached by hand on
  an event and can't be auto-added.
</Note>

## How a rule is configured

Each rule is one entry in the `formLogicRules` section of your company's
configuration, with three properties:

| Property       | Value                                                                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formNumber`   | The form template's `FM-XXXX` form number — the **ID** column on [Form templates](/app/admin/form-templates). The template must already be uploaded for the company. |
| `rank`         | A positive integer. Lower ranks are added first. No two rules may share a rank.                                                                                      |
| `addCondition` | A Jexl expression that decides whether to add the form. Leave it empty for "don't auto-add" (see below).                                                             |

<Note>
  **Only the forms you want auto-added are listed.** `formLogicRules` holds
  auto-add rules, not your forms. Every form template you've uploaded is available
  for the user to add by hand on the Forms step **whether or not** it has a rule —
  so a form that doesn't need any logic simply isn't listed. (A rule with an empty
  `addCondition` is allowed, but it behaves exactly like having no rule — the form
  isn't auto-added — while still using up a rank. There's no reason to add one.)
</Note>

<Tip>
  Technical teams can read and manage these rules programmatically. The
  [Configuration API](/api-reference/configuration/overview) exports your full
  configuration — `formLogicRules` included — as structured JSON and applies
  edited configuration back; it requires an [API key](/app/admin/api-keys) with
  the configuration-manager role.
</Tip>

<Steps>
  <Step title="Upload the form template first">
    A rule references a form by its **form number**, so the form template must
    already exist for the company. If a rule references a form that hasn't been
    uploaded, the configuration is rejected. See
    [Form templates](/app/admin/form-templates) for how templates are uploaded and
    managed.
  </Step>

  <Step title="Add a rule for each form you want auto-added">
    A form gets at most one rule. Set its `formNumber`, give it a unique `rank`,
    and write its `addCondition`. Forms that don't need auto-add logic are left
    out of `formLogicRules` entirely.
  </Step>

  <Step title="Apply the configuration">
    The rules are validated along with the rest of the configuration; any problem
    with a rule is reported before anything is saved. An export returns the rules
    back out, so you can always see exactly what's configured.
  </Step>
</Steps>

### Writing conditions

`addCondition` is a [Jexl](https://github.com/TomFrost/jexl) expression —
the same kind you already use for field **display** and **required** conditions.
It is evaluated against the quote's field values, and the form is added only when
the expression is **true**.

* Reference fields by their **bare reference ID** (no `quote.` prefix), exactly as
  in display/required conditions — e.g. `state == 'CA'` or
  `vehicleCount > 5`.
* Field references are type-checked when the configuration is applied, so a
  misspelled field name is caught before anything is saved. At runtime, a
  condition that can't be resolved (for example, a field with no value yet) is
  treated as **false** — the form simply isn't added.

An empty condition has a specific meaning:

| `addCondition`         | Behavior                                                                                                                            |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Empty** (or omitted) | The form is **not** auto-added — same as not listing it at all. It stays available for the user to add by hand from the Forms step. |
| **`true`**             | "Always add" — the form is added to every quote.                                                                                    |
| Any expression         | The form is added only on quotes where the expression evaluates true.                                                               |

### Rules and limits

Validation enforces a few constraints so the rule set stays unambiguous:

* **One rule per form.** Two rules referencing the same form number are rejected
  (*"each form may have at most one rule"*).
* **Unique ranks.** Two rules with the same rank are rejected (*"ranks must be
  unique"*).
* **Eligible forms only.** A rule may reference a **Quote** or **Policy** form.
  Referencing a **Claim/Incident** form is rejected (*"Forms logic can only add
  Quote or Policy forms"*).
* **The form must exist.** Referencing a form number with no uploaded template is
  rejected (*"…does not exist for this company. Upload the form template first,
  then re-import."*).

Each error names the offending rule, so it can be fixed and re-applied.

## How it behaves in the quote flow

When someone builds a quote, the rules run **once** and stage the matching forms
onto the quote — you'll see them appear under **Selected Forms** on the Forms
step.

<CardGroup cols={2}>
  <Card title="Runs once per quote" icon="rotate-right">
    Auto-add happens once, while the quote is still a draft — either when the
    Forms step is opened, or at the first save if that step was skipped. A quote
    that's already been saved is never re-evaluated.
  </Card>

  <Card title="Respects your changes" icon="hand">
    Because it never re-runs, anything you do afterward sticks. Remove an
    auto-added form and it stays removed when you reopen the quote; the rules
    won't put it back.
  </Card>
</CardGroup>

Forms appear in the order they were added. A clean auto-add comes out in **rank
order**, because the rules are evaluated and the forms created lowest-rank-first.

<Note>
  Because rules evaluate only once, changing an answer **after** the forms have
  been added won't update the form set on its own. Use the **Add Recommended
  Forms** button (below) to re-apply the rules.
</Note>

## The "Add Recommended Forms" button

The Forms step's **Selected Forms** card has an **Add Recommended Forms** button
(the <Icon icon="list-check" /> icon). It's the manual escape hatch for the cases
auto-add doesn't cover on its own:

* A quote that was **saved before** the form set was complete (auto-add only runs
  on a fresh draft).
* **Re-applying the rules** after you've changed an answer that a condition
  depends on.
* Pulling in recommended forms on a quote where they were never added.

Press it and the rules re-run against the quote's **current** answers. Any
recommended form that isn't already in the list is added; forms already present
are left alone (so it's safe to press more than once). You'll get a confirmation
toast — *"N recommended forms added."* — or, when there's nothing new to add,
*"No additional recommended forms to add."*

<Note>
  The button only **adds** forms — it never removes one you've taken off. It
  de-duplicates against what's currently shown, so a form you removed and want
  back will be re-added, while forms still in the list aren't duplicated.
  Re-added forms land at the **end** of the list rather than back in their
  original positions — but among themselves they keep **rank order**.
</Note>

## Putting it together

A typical rule set for an auto setup might look like:

```json theme={null}
"formLogicRules": [
  { "formNumber": "FM-0001", "rank": 1, "addCondition": "true" },
  { "formNumber": "FM-0002", "rank": 2, "addCondition": "state == 'CA'" }
]
```

On every quote, **FM-0001** is added first. **FM-0002** is added next, but only
when the quote's state is California. Any other uploaded form — say a rider the
user picks only occasionally — isn't listed here at all; it stays available to add
by hand on the Forms step.