---
title: "Create a one-hour, single-template preparation session"
method: POST
path: "/api/v1/template-preparation-sessions"
tags: ["Template Preparation"]
---

# Create a one-hour, single-template preparation session

`POST /api/v1/template-preparation-sessions`

## Request

- Base URL: `https://api.korala.ai`
- URL: `https://api.korala.ai/api/v1/template-preparation-sessions`
- Auth: API key in header `X-API-Key`

Call from your server. Without templateId, creates an inactive PDF template with configured signer roles. With templateId, opens a scoped editing draft of an existing PDF in the key mode and publishes to the original ID on save. Browser access can only prepare that template. In review mode your backend supplies the locked field definitions. API credentials must never reach the browser.

## Request body

- CreateTemplatePreparationDto
  - `signerRoles` CreateSignerRoleDto[]: Backend-defined signer roles. Names must be unique. When reopening, names and signing orders must match the existing template.
    - `name` string, required
    - `signingOrder` number
  - `fields` TemplatePreparationFieldDto[]: Required in review mode. Your backend defines the immutable fields; the browser can adjust geometry and remove explicitly removable repeated text placements.
    - `valueKey` string: Links repeated text fields for the same signer. Signer edits or clears one occurrence to update every field with this valueKey. Independent of the merge variable used for prefills.
    - `options` string[]: Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.
    - `groupKey` string: Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification.
    - `groupRequired` boolean: Require at least one member of this field's group to be selected before signing can complete.
    - `removable` boolean: Allow removing this repeated text placement. Requires a valueKey shared by multiple definitions for the same signer. At least one placement and one required placement (when configured) must remain.
    - `fieldType` 'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio', required
    - `signerRoleName` string: Owning role name. Required when the session has multiple signer roles.
    - `label` string, required
    - `mergeFieldName` string, required: Unique stable field key chosen by your backend.
    - `required` boolean, required
    - `signingDate` boolean: Automatically use the signing date. Date fields only.
  - `mode` 'full' | 'review'
  - `templateId` string: Existing uploaded PDF template to edit. Must have signer roles and match the API key mode.
  - `name` string: Required for a new template; optional when editing templateId.
  - `roleName` string
  - `parentOrigin` string, required: Exact origin of the embedding application.

## Response `201`

- TemplatePreparationSessionDto
  - `token` string, required
  - `templateId` string, required
  - `embedUrl` string, required
  - `expiresAt` string, required

---

[API](https://skmtc.dev/korala/apis/korala-public-api.md) · [All operations](https://skmtc.dev/korala/apis/korala-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korala/apis/korala-public-api/revisions/5c4d7810c507?raw)