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), quote-bind-flow (Policy), insured (Insured), or submission (Submission). A submission template’s tags read the Submission as submission.<field>, including its exposures list.
  • 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).
  • Form packet — the documents issued together on a quote or policy (when a quote is completed or bound, or a set is issued on a policy), merged into one PDF that never changes. See Form packets.
  • Recommended forms — the forms a company’s auto-added forms rules pick for a quote. A quote created through the entities API gets its quote forms generated and attached when it is created, and its policy forms when it is bound with bindForms: true.

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.
List Forms requires form-template.view; Download Form requires form.download. To download a quote’s or policy’s packet, list its packets with List Form Packets, then get a signed URL to the merged PDF with Get Form Packet Download URL. Only an issued packet downloads. A packet is pending for a few seconds after a bind or an issuance, and downloading it then returns 409.

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=. The deprecated bound compatibility key remains present and is always false; issued history lives in Packet Records rather than a per-form bound copy.
  • List Form Packets (GET /forms/packets?entityType=&entityId=) — list the packets issued on one quote or policy, newest first, each with its documents in page order. Requires form.view plus quote.view or policy.view.
  • Get Form Packet Download URL (GET /forms/packets/{packetId}/download-url) — get a signed URL to an issued packet’s merged PDF. Requires form.download plus quote.view or policy.view.
  • 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 Working Document, plus a refresh of its cached smart-tag metadata.
  • 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 Working Document.
  • Rename Form (PATCH /forms/{number}) — change a form’s display name (template or static) by its FM-XXXX number. Only the name changes: the number, category, version, and file stay the same, so forms-logic rules stay bound. Requires form-template.edit.
  • 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.

Import historical documents

For quotes and policies, use Import Historical Form Packet to attach issued PDF documents without a template. Supply the original issuance moment as issuedAt in Unix milliseconds, an ordered documents array, and a stable caller-generated packetId. Store that id with the source record and reuse it on retries: identical requests return the same packet, while changed evidence or metadata returns a conflict. Importing does not run completion or binding and does not alter the entity’s working forms. The existing Forms tab shows the packet as Historical with its original date and a separate reconstruction date. Each member PDF is retained unchanged. A single preassembled packet can be sent as one document to preserve the entire file byte for byte. Multiple documents are concatenated in order for the packet download. Use the returned id with List Form Packets and Get Form Packet Download URL. For claims and incidents, use Upload Event Form with eventId, fileName, and fileBase64. This attaches a working form in the existing event Forms tab, without creating an issued packet. Send an Idempotency-Key to avoid duplicate uploads when retrying within 30 days; retain the returned form id for later import reconciliation. The PDF can be previewed, downloaded, and deleted, and has no document editor. Both endpoints accept readable, unencrypted PDFs up to 20 MB (combined for a packet). Upload permissions are form.create plus the target record’s view permission.