---
title: "Replace template document"
method: POST
path: "/templates/{id}/replace-document"
tags: ["Templates"]
---

# Replace template document

`POST /templates/{id}/replace-document`

Replaces the PDF document of an existing template while preserving all field placements. The replacement document must have the same page count and matching page dimensions (within 1pt tolerance) as the original.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `document` string, required — Base64-encoded PDF or DOCX 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.

## Response `200`

Document replaced 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` — Validation error (page count mismatch, dimension mismatch, invalid document)
- `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)