Skip to main content
The Forms API lets you upload two kinds of form into a company instance, each assigned a category: a form template (a .docx with smart tags, validated before commit) and a static form (a .pdf used as-is).

​
Key Concepts

  • Form template — a DOCX document containing smart-tag anchors (placeholders) that get resolved against entity data when a form is generated.
  • Static form — a PDF used as-is (a certificate, handout, etc.). PDFs cannot carry smart tags, so nothing is substituted when a form is generated from one.
  • Smart tag — a placeholder that maps to a configured field. A field tag is identified in the document as AIIFmv1Fld followed by a 16-character hash of the field’s reference id (e.g. the namedInsured field → AIIFmv1Fld9E5D74B94AC85D40); copy identities from the form editor’s smart-tag sidebar rather than deriving them by hand. The older readable form (AIIFmv1<ReferenceId>, e.g. AIIFmv1NamedInsured) is retired: uploads carrying it are rejected with a per-tag error naming the exact current identity. Smart tags live only in DOCX templates; PDFs carry none.
  • Category — selects which entity data source resolves the form’s smart tags (and classifies static forms the same way). Required on upload for both kinds, and must be one of event (Claim/Incident), quote-flow (Quote), or quote-bind-flow (Policy).
  • Generated form — an instance produced from a form in the library against a specific record (a quote, policy, or claim). Generated forms are listed separately from the library (see List Generated Forms below).

​
Validation

For a form template (DOCX), the upload validates every embedded smart tag against the catalog of tags available for the chosen category. If any tag is unknown, named with the retired legacy AIIFmv1<ReferenceId> style, not enabled as a smart tag, on the wrong category, or maps to an unsupported field type, the entire upload is rejected with a 400 whose details list one entry per offending tag — nothing is written. This makes it safe to migrate forms between instances: a tag whose field is missing on the destination fails loudly at upload time instead of silently producing a form full of raw placeholders. A static form (PDF) carries no smart tags, so there is nothing to validate — it is committed directly.

​
Constraints

  • Templates are DOCX; static forms are PDF. Only DOCX carries the OOXML smart-tag anchors the validator inspects; each endpoint accepts only its own file type.
  • The file is sent as base64 in the request body (for a template, the bytes must reach the API so the tags can be validated before commit).

​
Retrieval

Forms are also readable, so you can round-trip them (export → edit → re-upload via the replace endpoints) or back up a company’s library:
  • List Forms returns every form’s number alongside its kind (template vs static), category, version, and timestamps — the number is what the download, replace, and delete endpoints address.
  • Download Form returns a short-lived signed URL to the current version’s original uploaded file (the DOCX for templates, the PDF for static forms). The bytes come straight from cloud storage, never through the API.
Both require the forms:read permission.

​
API Endpoints

  • List Forms (GET /forms) — list a company’s forms (one summary per form’s current version), paginated (?page=/?pageSize=, with a totalCount) and optionally filtered by ?category= and/or ?kind=.
  • List Generated Forms (GET /forms/generated) — list the forms generated from the library against specific records, paginated (?page=/?pageSize=, with a totalCount) and optionally filtered by ?category=. Each item reports whether a bound copy exists (bound).
  • Download Form (GET /forms/{number}) — get a signed URL to download a form’s current-version file, by its FM-XXXX number (works for templates and static forms alike).
  • Upload Form Template (POST /forms/template) — upload a .docx template under a category, validating its smart tags.
  • Upload Static Form (POST /forms/static) — upload a .pdf static form under a category (no smart-tag validation).
  • Replace Form Template (PUT /forms/template/{number}) — replace a DOCX template’s content in place (a new version under the same number). Keeps the same identity, name, and category, so forms-logic rules stay bound. Same DOCX + smart-tag validation as upload. Same-type only (a static PDF uses the endpoint below).
  • Replace Static Form (PUT /forms/static/{number}) — replace a static PDF form’s content in place (a new version under the same number). No smart-tag validation (PDFs carry none). Same-type only (a DOCX template uses the endpoint above).
  • Touch Form Template (POST /forms/template/{number}/touch) — bring a template’s current version up to date in place: converges legacy-style smart-tag anchors to the current hashed identity format without creating a new version. Idempotent; the response reports what (if anything) changed.
  • Touch Generated Form (POST /forms/generated/{id}/touch) — the same convergence for one generated form’s editable draft, plus a refresh of its cached smart-tag metadata. A finalized (bound) copy is never altered.
  • Audit Form Template Smart Tags (GET /forms/template/{number}/smart-tag-audit) — read-only classification of every smart-tag identity a template carries against the company’s current field configuration; finds tags that would render unfilled on generated documents. Nothing is written.
  • Audit Generated Form Smart Tags (GET /forms/generated/{id}/smart-tag-audit) — the same read-only classification for one generated form’s editable draft.
  • Delete Form (DELETE /forms/{number}) — soft-delete a form (template or static) by its stable FM-XXXX number. Removes every version from the library; forms already generated from it keep working. A forms-logic rule that still references the number blocks deletion with 409; remove the rule from the field-model configuration first.