---
title: "Comprehensive Template Update"
method: PUT
path: "/templates/{id}"
tags: ["Templates"]
---

# Comprehensive Template Update

`PUT /templates/{id}`

Comprehensive update of template including properties, users, fields, and reminders. Supports user deletion with field reassignment or deletion. All sections are optional but at least one must be provided.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `template_properties` object — Update template metadata and settings
    - `name` string
    - `description` string
    - `document` string, byte — Base64-encoded PDF or DOCX to replace document. DOCX files are automatically converted to PDF. For documents larger than 5 MB, use POST /documents and pass the document_id instead. (mutually exclusive with document_id)
    - `document_id` string, uuid — ID of a previously uploaded document (mutually exclusive with document). Obtain by calling POST /documents first.
    - `expiration_hours` integer
    - `settings` object
      - `allow_editing_before_sending` boolean
      - `attach_pdf_on_finish` boolean
      - `allow_download` boolean
      - `hand_drawn_only` boolean
      - `require_otp_verification` boolean, nullable
      - `disable_guided_navigation` boolean, nullable
      - `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.
  - `users` object[] — Upsert users (include id to update, omit to create)
    - `id` string, uuid — Omit for new users
    - `first_name` string, required
    - `last_name` string — Optional, but required if using full_name or last_name prefilled variables
    - `email` string, email, required
    - `designation` 'Signer' | 'Approver' | 'CC', required
    - `order` integer, required
    - `phone_number` string
    - `street_address` string
    - `city` string
    - `state_province` string
    - `postal_code` string
    - `country` string
    - `title` string
    - `company` string
  - `force_remove_conditions` boolean — When deleting users whose fields are referenced by conditions in other fields: if true, automatically remove the condition references; if false (default), the request will be rejected with an error.
  - `deleted_users` object[] — Users to delete with field handling strategy
    - `user_id` string, uuid, required
    - `field_action` 'delete' | 'reassign', required — What to do with fields assigned to this user
    - `reassign_to_user_id` string, uuid — Required when field_action is 'reassign'. Target user must have same designation.
  - `fields` object[] — Upsert fields (include id to update, omit to create)
    - `id` string, uuid — Omit for new fields
    - `type` 'signature' | 'text' | 'date' | 'checkbox' | 'dropdown' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required
    - `x` number, required — X position as percentage
    - `y` number, required — Y position as percentage
    - `width` number, required
    - `height` number, required
    - `page` integer, required
    - `required` boolean
    - `assigned_to_user_id` string, uuid
    - `options` string[] — For dropdown fields
    - `default_to_signing_date` boolean — For date fields
    - `multi_group_id` string, uuid — Group ID for mutually exclusive checkbox/radio button groups
    - `variable_name` string
    - `variable_defined_name` string, nullable — Human-readable custom field definition name. Can be used as an alternative to variable_name for targeting fields in template-based creation.
    - `required_conditions` ConditionSet — A set of condition groups with nested logic. The outer 'logic' operator combines groups, while each group's conditions use the opposite operator. Example: logic='and' means all groups must match, and within each group any condition can match (OR).
      - `logic` 'and' | 'or', required — Logical operator to combine groups. 'and' = all groups must match, 'or' = any group can match.
      - `groups` ConditionGroup[], required — Array of condition groups
        - `conditions` Condition[], required — Array of conditions within this group. Combined using the opposite of the parent ConditionSet's logic operator.
          - `field_id` string, uuid, required — ID of the field to evaluate
          - `operator` 'is_filled' | 'is_empty' | 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal', required — Comparison operator. 'is_filled'/'is_empty' don't require a value. Text operators: equals, not_equals, contains, not_contains. Numeric/date operators: greater_than, less_than, greater_than_or_equal, less_than_or_equal.
          - `value` union — Value to compare against. Not required for is_filled/is_empty operators.
            - string
            - number
    - `visibility_conditions` ConditionSet — A set of condition groups with nested logic. The outer 'logic' operator combines groups, while each group's conditions use the opposite operator. Example: logic='and' means all groups must match, and within each group any condition can match (OR).
      - `logic` 'and' | 'or', required — Logical operator to combine groups. 'and' = all groups must match, 'or' = any group can match.
      - `groups` ConditionGroup[], required — Array of condition groups
        - `conditions` Condition[], required — Array of conditions within this group. Combined using the opposite of the parent ConditionSet's logic operator.
          - `field_id` string, uuid, required — ID of the field to evaluate
          - `operator` 'is_filled' | 'is_empty' | 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal', required — Comparison operator. 'is_filled'/'is_empty' don't require a value. Text operators: equals, not_equals, contains, not_contains. Numeric/date operators: greater_than, less_than, greater_than_or_equal, less_than_or_equal.
          - `value` union — Value to compare against. Not required for is_filled/is_empty operators.
            - string
            - number
  - `reminders` object[] — Upsert reminders (include id to update, omit to create)
    - `id` string, uuid — Omit for new reminders
    - `hours` integer, required — Hours after sending before reminder
    - `all_users` boolean
    - `user_id` string, uuid — Required if all_users is false
    - `subject` string, required
    - `message` string, required

## Response `200`

Template updated successfully. Returns full template with all relationships.

- 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
- `404` — Not Found - Resource does not exist
- `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)