---
title: "Create Template"
method: POST
path: "/templates"
tags: ["Templates"]
---

# Create Template

`POST /templates`

Create a new template with a base64-encoded PDF document. The API automatically extracts the page count from the document.

## Request body

- object
  - `name` string, required — Template name
  - `description` string — Template description
  - `document` string, byte, required — Base64-encoded PDF or DOCX document. DOCX files are automatically converted to PDF. The API will automatically extract the page count from the document. For documents larger than 5 MB, use POST /documents and pass the document_id instead. (mutually exclusive with document_id)
  - `expiration_hours` integer — Hours until signing request expires
  - `settings` object
    - `allow_editing_before_sending` boolean — Allow editing fields before sending
    - `attach_pdf_on_finish` boolean — Attach completed PDF to completion email
    - `allow_download` boolean — Allow recipients to download the document
    - `hand_drawn_only` boolean — Require signers to hand-draw their signatures instead of using typed signatures
    - `require_otp_verification` boolean, nullable — Require signers to verify their email with a one-time code. null = inherit from workspace/company.
    - `disable_guided_navigation` boolean, nullable — Disable automatic scrolling to the next required field during signing. Inherits from workspace or company if not set.
    - `allow_presigning_download` boolean, nullable — Allow signers to download the original document before signing. Inherits from workspace or company setting when null.
    - `show_qr_code` boolean, nullable — Show a QR code on the signing page that lets signers continue on their phone. Inherits from workspace or company setting when null.
  - `document_id` string, uuid — ID of a previously uploaded document (mutually exclusive with document). Obtain by calling POST /documents first.

## Response `201`

Template created successfully

- Template
  - `id` string, uuid, required — Unique identifier for the template
  - `name` string, required — Template name
  - `description` string, nullable — Template description
  - `document_url` string, uri — Pre-signed URL to the PDF document. This is a time-limited signed URL for secure access - see document_url_expires_at for expiration time. Initial URLs are valid for 7 days; refreshed URLs are valid for 1 hour. Request a new template retrieval to get a fresh URL if expired.
  - `document_url_expires_at` string, date-time, nullable — ISO 8601 timestamp when the document_url will expire. After this time, the URL will return an access denied error. Fetch the template again to receive a fresh signed URL.
  - `page_count` integer — Number of pages in the document
  - `expiration_hours` integer — Hours until signing requests created from this template expire
  - `credit_cost` integer — Number of credits consumed when a signing request is sent from this template. Minimum value is 1.
  - `settings` SigningRequestSettings — Settings returned by the signing request list and detail endpoints. Templates use the TemplateSettings schema (no identity fields).
    - `allow_download` boolean — Whether recipients can download the document
    - `attach_pdf_on_finish` boolean — Whether to attach PDF when signing is complete
    - `allow_editing_before_sending` boolean — Whether the signing request can be edited before sending
    - `use_signing_order` boolean — Whether signing order is enforced among recipients. When true, signers receive the document in sequence based on their order. When false, all signers receive the document simultaneously.
    - `hand_drawn_only` boolean — When enabled, signers can only hand-draw their signatures and cannot use typed/font-based signatures
    - `send_signing_email` boolean — Whether to send signing request notification emails to signers
    - `send_finish_email` boolean — Whether to send completion email when all signers finish
    - `send_expiration_email` boolean — Whether to send expiration notification email when request expires
    - `send_cancellation_email` boolean — Whether to send cancellation notification email when request is cancelled
    - `require_otp_verification` boolean, nullable — Whether signers must verify their email with a one-time code before accessing the document. null = inherit from workspace/company setting.
    - `disable_guided_navigation` boolean, nullable — Disable automatic scrolling to the next required field during signing. Inherits from workspace or company if not set.
    - `allow_presigning_download` boolean, nullable — Allow signers to download the original document before signing. Inherits from workspace or company setting when null.
    - `show_qr_code` boolean, nullable — Show a QR code on the signing page that lets signers continue on their phone. Inherits from workspace or company setting when null.
    - `identity_editable_fields` string[], nullable — Identity fields signers may edit before signing (e.g. ["name", "company"]). null = disabled. When set, a confirmation dialog lets signers edit the specified fields.
    - `notify_identity_change_email` boolean — Send an email notification when a signer changes their identity.
  - `recipients` TemplateUser[] — Template recipients (included in GET single template)
    - `id` string, uuid, required — Unique identifier for the template user
    - `name` string — Recipient name (combined first and last name)
    - `email` string, email, required — Recipient email address
    - `first_name` string, nullable, required — Recipient first name
    - `last_name` string, nullable — Recipient last name
    - `designation` 'Signer' | 'Approver' | 'CC', required — Role of the recipient. Signer signs the document, Approver approves with approval fields, CC receives a copy when complete.
    - `order` integer, required — Order in which the recipient should sign
    - `phone_number` string, nullable — Recipient phone number
    - `street_address` string, nullable — Recipient street address
    - `city` string, nullable — Recipient city
    - `state_province` string, nullable — Recipient state or province
    - `postal_code` string, nullable — Recipient postal code
    - `country` string, nullable — Recipient country
    - `title` string, nullable — Recipient job title
    - `company` string, nullable — Recipient company name
    - `required_fields` string[] — List of recipient data fields required for sending (based on template fields with variable_name mappings). Always includes 'email' and 'first_name'.
    - `missing_fields` string[] — List of required fields that are currently empty for this recipient
    - `required_read_only_fields` object[] — List of required read-only fields that need pre-filled values before sending
      - `variable_name` string, nullable — Variable name of the read-only field
      - `variable_defined_name` string, nullable — Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise.
      - `field_type` string — Type of the field (text, date, etc.)
    - `ready_to_send` boolean — Whether this recipient has all required data filled in for sending
  - `fields` TemplateField[] — Template fields (included in GET single template)
    - `id` string, uuid, required — Unique identifier for the field
    - `type` 'text' | 'signature' | 'date' | 'checkbox' | 'dropdown' | 'radio_buttons' | 'number' | 'text_area' | 'file' | 'initial' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required — Type of the field
    - `required` boolean — Whether the field is required
    - `recipient_id` string, uuid, nullable — ID of assigned recipient
    - `variable_name` string, nullable — Variable name for field (used in templates)
    - `variable_defined_name` string, nullable — Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise.
    - `position` object — Position and dimensions of the field on the document. All values are percentages (0-100). The field must fit within the page: x + width <= 100 and y + height <= 100.
      - `x` number — X coordinate of field position (percentage, 0-100)
      - `y` number — Y coordinate of field position (percentage, 0-100)
      - `width` number — Width of the field (percentage, 0-100). Note: x + width must be <= 100
      - `height` number — Height of the field (percentage, 0-100). Note: y + height must be <= 100
    - `page_number` integer, nullable, required — Page number where the field is located (1-indexed). Must not exceed the document's total page count.
    - `dropdown_options` union — Options for dropdown fields
      - string[]
      - object
    - `multi_group_id` string, uuid, nullable — Group ID for linking multiple checkbox or radio button fields together. Fields sharing the same multi_group_id behave as a mutually exclusive group (like radio buttons) - selecting one automatically deselects the others in the group. Use the same UUID across multiple fields to create a group where only one option can be selected at a time.
    - `date_default` string, date, nullable — Default date value for date fields (ISO 8601 format, e.g., '2024-01-15')
    - `date_signing_default` boolean — Use signing date as default for date fields
    - `format_rules` DateFormatRules — Formatting rules for date fields. Specifies how date values should be displayed and formatted.
      - `dateFormat` 'MM/dd/yyyy' | 'dd/MM/yyyy' | 'yyyy-MM-dd' | 'MMMM dd, yyyy' | 'MMM dd, yyyy' | 'dd MMMM yyyy' — Date format pattern. Use predefined formats or custom patterns with: yyyy (4-digit year), MM (2-digit month), dd (2-digit day), MMMM (full month name), MMM (abbreviated month name), HH (24-hour), mm (minute), ss (second). Examples: 'MM/dd/yyyy' displays as 01/31/2024, 'MMMM dd, yyyy' displays as January 31, 2024.
      - `fontSize` integer — Optional starting/maximum font size in pixels for the rendered field value. Text still auto-shrinks to fit the field box. Omit for automatic sizing. Values outside 8-48 are clamped.
    - `validation_rules` FieldValidationRules, nullable — Validation rules for field values. Reserved for future use - currently not enforced for any field types.
    - `read_only` boolean — Whether this field is read-only (pre-filled before signing)
    - `read_only_value` string, nullable — Static value for read-only fields
  - `created_date` string, date-time, required — Template creation timestamp
  - `updated_date` string, date-time — Template last update timestamp

## Other responses

- `400` — Bad Request - Validation failed
- `401` — Unauthorized - Invalid or missing API key
- `429` — Too Many Requests - Rate limit exceeded

---

[API](https://skmtc.dev/firma/apis/firma-partner-api.md) · [All operations](https://skmtc.dev/firma/apis/firma-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/firma/firma-partner-api/revisions/5c03d6a9d080/schema)