> ## Documentation Index
> Fetch the complete documentation index at: https://developer.demand-iq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts & e-signature

> Import contract templates, configure signing requirements, and collect typed signatures during presentations.

Contracts let homeowners sign agreements directly inside a presentation. You upload a contract document, AI Presentations converts it to a template with variable placeholders, and viewers sign with a typed signature at the end of the presentation.

## How it works

1. **Import** a contract (PDF or Word) — AI Presentations analyzes the full document and identifies variables like names, dates, and addresses
2. **Edit the template** — refine the markdown template, add disclosures, and configure signing requirements
3. **Publish** — once published, the contract appears as a signing step in the presentation
4. **Viewer signs** — the homeowner reviews the contract with their details filled in, types their name as a signature, and submits

Signed documents are stored with a full audit trail including timestamp, user agent, and the exact contract text the viewer agreed to.

## Import a contract document

In the template editor, open the **Actions** tab and click **Import Contract**.

Upload a PDF or Word document (max 10 MB). Both modern (`.docx`) and legacy (`.doc`) Word formats are supported. AI Presentations converts legacy `.doc` files to `.docx` automatically before analysis. AI Presentations uses AI to analyze the entire document and convert it to a markdown template, preserving all sections, clauses, and legal language rather than summarizing. It detects variables like `{{full_name}}` and `{{address}}` that get replaced with the homeowner's real information when the contract is presented.

After import, you'll see:

* The generated **markdown template** — editable
* A list of **detected variables** that will be auto-filled from homeowner data

## Configure the template

Each contract template (called an "action config") has several fields:

* **Template Markdown** — the contract text with `{{variable}}` placeholders. Supports standard markdown formatting.
* **Disclosures Markdown** — optional fine print shown below the contract
* **Requirements** — controls what the signer must do:
  * Typed signature required
  * Signature must match the expected customer name
  * "I agree" checkbox with custom label
* **Rep Name** — the sales representative name shown on the contract
* **Status** — `draft` or `published`. Only published templates are shown to presentation viewers.

## Template variables

Variables in double curly braces are replaced with real values when a homeowner views the contract. Available variables include:

| Variable           | Source                 |
| ------------------ | ---------------------- |
| `{{full_name}}`    | Homeowner's full name  |
| `{{first_name}}`   | Homeowner's first name |
| `{{last_name}}`    | Homeowner's last name  |
| `{{address}}`      | Street address         |
| `{{city}}`         | City                   |
| `{{state}}`        | State                  |
| `{{zip}}`          | ZIP code               |
| `{{company_name}}` | Your company name      |
| `{{rep_name}}`     | Sales rep name         |

Product selections (from product pricing slides) are also available — if the homeowner selected a product card during the presentation, the selected product name and price are included. Selection works for any card on the slide, whether it's one of the good/better/best tiers or a journey-backed extra card.

## Signing flow

When a viewer reaches the signing step:

1. They see the contract with all variables filled in
2. If the agreement checkbox is enabled in requirements, they check it to confirm
3. They type their full name as a signature
4. The typed signature is validated against the homeowner's name — this check is always enforced
5. On successful signing, an audit-trailed document is created and a `contract.signed` event is emitted

## Multiple contract templates per template

A template can have multiple action configs (contract templates), but only one should be published at a time. Pass the `configId` of the template you want to sign against when calling the signing endpoint. If you omit `configId`, AI Presentations signs against a built-in default template — set `configId` explicitly to use your template's published contract.

## API reference

Key contract endpoints:

* `POST /api/contracts/import` — upload and analyze a contract document
* `GET/POST /api/decks/{deckId}/action-configs` — list or create contract templates
* `GET/PUT/DELETE /api/decks/{deckId}/action-configs/{configId}` — manage a specific template
* `GET /api/presentations/{presentationId}/sign-contract` — fetch the template, requirements, and homeowner context to render the contract client-side
* `POST /api/presentations/{presentationId}/sign-contract` — submit a signature

Both verbs require an `x-presentation-token` scoped to this presentation, matching the sibling `events` and `appointment` routes. Requests without a valid token get a `401`. Mint the token with `POST /api/presentations/{presentationId}/events-token`. The typed signature is also validated against the homeowner's name on the presentation, so a caller holding a token still cannot sign under a different name.

Signing a soft-deleted presentation is refused with `404`, even when the caller holds a token minted before the delete (tokens stay cryptographically valid for their full 24-hour TTL).

The server keeps only whitelisted keys from `variables` before storing them. Non-whitelisted keys and non-string values are silently dropped, so a caller cannot persist arbitrary fields onto `resolvedVariables`. See the **API Reference** tab for the exact allow-list and full request and response details.