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

# Trigger template

> Generate one or more documents from **published** templates.

Each entry in `list` names a template key and may override its stored `output` configuration. The shared `payload` object is the data context for **angular expression evaluation**: every key in the payload becomes an identifier available to tags inside the template's source DOCX, to the `output.name` filename template, to `signatories[].name`/`email`, and (as `<key>.value` facts) to `sub_templates[].conditions`. Expressions support nested property access (`{client.address.city}`), operators (`{subtotal + tax}`, `{is_overdue ? "OVERDUE" : ""}`), condition blocks (`{#discount > 0}…{/}`), loops (`{#line_items}{description} — {qty * unit_price}{/line_items}`), and the built-in filters.

**This is an asynchronous operation.** The `200` response confirms each job was queued (or reports per-template validation errors) and returns the document `subject`. A document record is created immediately with `output: null`; the trigger consumer then fetches the published template and its matching sub-templates, renders them against the payload, merges the results, and updates the record with `output.key` (the storage URI of the generated file) — or with `errors` if rendering failed. Poll `GET /documents/{key}` to observe completion. If the template defines signatories, the signature request is dispatched automatically after rendering succeeds (each signatory starts as `DRAFT`, moving to `SENT` once the request is created).

The generated file is written to `{store}://{bucket}/{filepath}` where trigger-level `output` overrides take precedence over the template's stored `output`. Buckets may target the object store (`obj://`, default) or the key-value store (`kv://`).

**Built-in HTML report.** A template key starting with `builtin.` (for example `builtin.report`) is resolved from templates shipped with the platform, with no per-account setup. Built-in templates render text/html to text/html: you supply the report content, the template owns the layout, and the account's document theme supplies the brand (accent colour, fonts, footer, and the account logo, or the platform logo when the account has none). The content is sanitised: scripts, event handlers, styles, remote resources and unsafe links are removed.



## OpenAPI

````yaml /api-reference/endpoint/documents/openapi.json post /file-generator/templates/trigger
openapi: 3.1.0
info:
  title: Documents API
  description: >-
    Document templates, generated documents, e-signature requests, and checkbox
    approvals. Template and document routes are served under `/file-generator`,
    approval routes under `/workspaces/approvals`.
  version: 1.2.0
servers:
  - url: https://api.quiva.ai
    description: Production API server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Templates
    description: >-
      Template lifecycle — create, read, publish, validate, trigger, and delete
      document templates. Templates follow a **draft → published** model: writes
      (`POST`, `PATCH`) always target the draft version, and `POST
      /templates/{key}/publish` promotes the draft. Document generation only
      ever uses the published version, so drafts can be edited safely without
      affecting production output. A template's `source` is a DOCX file
      containing angular-expression tags rendered at trigger time.
  - name: Documents
    description: >-
      Document lifecycle — read, update, and delete generated documents. A
      document record is created immediately when a template is triggered and is
      updated asynchronously: first with the generated `output.key` (an `obj://`
      or `kv://` storage URI) or `errors`, then with `signatures` progress as
      signatories sign.
  - name: Signatures
    description: >-
      E-signature workflows powered by HelloSign (Dropbox Sign). Signature
      requests are created automatically when a triggered template defines
      `signatories`. Each signatory tracks a status lifecycle of `DRAFT → SENT →
      SIGNED`, with `EXPIRED` (validity window elapsed) and `FAILED`
      (delivery/signing error) as terminal failure states. Embedded signing URLs
      can be generated for signatures created in embedded mode.
  - name: Approvals
    description: Checkbox approval of a workspace file, recorded as e-signature evidence.
  - name: Generation
  - name: Template Source
paths:
  /file-generator/templates/trigger:
    post:
      tags:
        - Templates
      summary: Trigger template
      description: >-
        Generate one or more documents from **published** templates.


        Each entry in `list` names a template key and may override its stored
        `output` configuration. The shared `payload` object is the data context
        for **angular expression evaluation**: every key in the payload becomes
        an identifier available to tags inside the template's source DOCX, to
        the `output.name` filename template, to `signatories[].name`/`email`,
        and (as `<key>.value` facts) to `sub_templates[].conditions`.
        Expressions support nested property access (`{client.address.city}`),
        operators (`{subtotal + tax}`, `{is_overdue ? "OVERDUE" : ""}`),
        condition blocks (`{#discount > 0}…{/}`), loops
        (`{#line_items}{description} — {qty * unit_price}{/line_items}`), and
        the built-in filters.


        **This is an asynchronous operation.** The `200` response confirms each
        job was queued (or reports per-template validation errors) and returns
        the document `subject`. A document record is created immediately with
        `output: null`; the trigger consumer then fetches the published template
        and its matching sub-templates, renders them against the payload, merges
        the results, and updates the record with `output.key` (the storage URI
        of the generated file) — or with `errors` if rendering failed. Poll `GET
        /documents/{key}` to observe completion. If the template defines
        signatories, the signature request is dispatched automatically after
        rendering succeeds (each signatory starts as `DRAFT`, moving to `SENT`
        once the request is created).


        The generated file is written to `{store}://{bucket}/{filepath}` where
        trigger-level `output` overrides take precedence over the template's
        stored `output`. Buckets may target the object store (`obj://`, default)
        or the key-value store (`kv://`).


        **Built-in HTML report.** A template key starting with `builtin.` (for
        example `builtin.report`) is resolved from templates shipped with the
        platform, with no per-account setup. Built-in templates render text/html
        to text/html: you supply the report content, the template owns the
        layout, and the account's document theme supplies the brand (accent
        colour, fonts, footer, and the account logo, or the platform logo when
        the account has none). The content is sanitised: scripts, event
        handlers, styles, remote resources and unsafe links are removed.
      operationId: triggerTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerTemplateRequest'
            example:
              payload:
                client_name: Acme Corp
                client_email: billing@acme.com
                invoice_number: INV-2026-014
                currency: EUR
                line_items:
                  - description: Consulting
                    qty: 10
                    unit_price: 120
                  - description: Support retainer
                    qty: 1
                    unit_price: 800
                subtotal: 2000
                tax: 400
              list:
                - template: invoice-template
                  output:
                    folder: invoices.2026
      responses:
        '200':
          description: >-
            Trigger jobs queued. The response is per-template: entries with a
            `subject` were queued successfully (the subject identifies the
            document record to poll); entries with `errors` failed validation
            and no job was queued for them. A `200` therefore does not guarantee
            every template was triggered — check each result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerTemplateResponse'
              example:
                - template: invoice-template
                  subject: ms.document.document.invoices.2026.invoice-INV-2026-014.pdf
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    TriggerTemplateRequest:
      type: object
      required:
        - payload
        - list
      properties:
        payload:
          type: object
          additionalProperties: true
          description: >-
            Data context (source) for all template expressions. **No schema
            required — completely flexible and user-defined.** Every key in the
            payload becomes an identifier available in template tags. Example:
            payload `{"client_name": "Acme", "invoice_number": "INV-001"}` makes
            `{client_name}` and `{invoice_number}` available in the template.
            Nested objects and arrays are fully traversable:
            `{client.address.city}`, `{items.0.price}`, `{#items}...{/items}`.
            Missing fields render as empty (not errors) — use conditionals like
            `{#field}...{/}` to handle optional data. Structure your payload to
            match the identifiers referenced in your template; the API does not
            validate field matching.
          example:
            client_name: Acme Corp
            client_email: billing@acme.com
            invoice_number: INV-2024-001
            amount: '5000.00'
        list:
          type: array
          items:
            $ref: '#/components/schemas/TemplateTriggerItem'
          description: >-
            One or more template trigger entries. Each queues an independent
            generation job rendered against the shared `payload`; per-entry
            `output` overrides take precedence over the template's stored output
            configuration.
    TriggerTemplateResponse:
      type: array
      items:
        $ref: '#/components/schemas/TriggerResult'
    TemplateTriggerItem:
      type: object
      required:
        - template
      properties:
        template:
          type: string
          description: Key of the published template to trigger.
          example: invoice-template
        output:
          $ref: '#/components/schemas/TriggerOutputOverride'
    TriggerResult:
      type: object
      required:
        - template
      properties:
        template:
          type: string
          description: Template key that was triggered.
          example: invoice-template
        subject:
          type: string
          description: >-
            Messaging subject of the queued document
            (`ms.document.document.{sanitised filepath}`). Present on success —
            poll `GET /documents/{key}` with the corresponding key to observe
            generation progress.
          example: ms.document.document.invoices.2026.invoice-INV-2026-014.pdf
        errors:
          type: array
          items:
            type: string
          description: Validation or processing errors. Present on failure.
          example:
            - >-
              Document template with key: invoice-template does not have a
              template source
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: '"key" is required'
    TriggerOutputOverride:
      type: object
      properties:
        name:
          type: string
          example: invoice-{invoice_number}
        content_type:
          type: string
          example: application/pdf
        bucket:
          type: string
          example: microstrate-documents
        folder:
          type: string
          example: invoices.2024
      description: >-
        Per-trigger overrides for the template's stored `output` configuration.
        Any field provided here takes precedence; omitted fields fall back to
        the template, then to service defaults.
  responses:
    BadRequest:
      description: Invalid or missing request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: '"key" is required'
    Unauthorized:
      description: Missing or invalid Authorization header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Authorization header with a bearer token is required
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.