> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace template 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.



## OpenAPI

````yaml api-reference/v01.20.00/openapi-v01.20.00.json post /templates/{id}/replace-document
openapi: 3.0.3
info:
  title: Firma Partner API
  description: >-
    RESTful API for document signing and template management.


    **Authentication**: All endpoints require API key authentication via the
    `Authorization` header. Use your API key directly without any prefix (e.g.,
    `your-api-key`). The Bearer prefix is optional but not required.


    **Security Features**:

    - Input validation using Zod schemas with detailed field-level error
    messages

    - RSA-256 signed JWT tokens for embedded template access


    **Rate Limiting**: Rate limits are tiered based on operation type:

    - Read operations (GET): 200 requests per minute

    - Write operations (POST/PUT/PATCH/DELETE): 120 requests per minute

    - Webhook CRUD operations: 60 requests per minute

    - Webhook test: 10 requests per minute

    - API key regeneration/expiration: 1 request per minute

    - Webhook secret rotation: 1 request per minute


    When rate limits are exceeded, the API returns a `429 Too Many Requests`
    response with headers:

    - `X-RateLimit-Limit`: Maximum requests per minute for this endpoint

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets

    - `Retry-After`: Seconds until retry is allowed


    **Error Handling**: All errors return structured JSON responses with `error`
    (human-readable message), `code` (machine-readable identifier), and
    `details` (field-level validation errors when applicable).


    **Embedded Template Integration**: The Firma Template Editor can be embedded
    in your application using a standalone JavaScript library.


    ```html

    <!-- Load the Firma Template Editor library -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Generate JWT token via API first

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Initialize editor with JWT token
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    ```
  version: 01.20.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: Production API - Recommended (Current)
  - url: https://api.firma.dev/api/v1
    description: Production API - Planned
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Company information and settings
  - name: Workspaces
    description: Workspace management operations
  - name: Templates
    description: Template management operations
  - name: Signing Requests
    description: Document signing request operations
  - name: Custom Fields
    description: >-
      Custom field definition management for workspaces, templates, and signing
      requests
  - name: Webhooks
    description: Webhook configuration and management
  - name: JWT Management
    description: JWT token generation and revocation for embedded templates
  - name: Workspace Settings
    description: Workspace configuration and settings
  - name: Email Domains
    description: >-
      Email domain setup and verification for sending signing request emails
      from custom domains
  - name: Email Templates
    description: >-
      Email template management for workspace and company-level customization of
      signing request notifications
  - name: Legacy
    description: Deprecated endpoints maintained for backward compatibility
paths:
  /templates/{id}/replace-document:
    post:
      tags:
        - Templates
      summary: Replace template document
      description: >-
        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.
      parameters:
        - name: id
          in: path
          required: true
          description: Template ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - document
              properties:
                document:
                  type: string
                  description: >-
                    Base64-encoded PDF or DOCX document. DOCX files are
                    automatically converted to PDF.
      responses:
        '200':
          description: Document replaced successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Rate limit: 120 requests per minute'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: >-
            Validation error (page count mismatch, dimension mismatch, invalid
            document)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Template:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the template
        name:
          type: string
          description: Template name
          maxLength: 255
        description:
          type: string
          description: Template description
          nullable: true
        document_url:
          type: string
          format: uri
          description: >-
            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:
          type: string
          format: date-time
          nullable: true
          description: >-
            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:
          type: integer
          minimum: 1
          description: Number of pages in the document
        expiration_hours:
          type: integer
          minimum: 1
          default: 168
          description: Hours until signing requests created from this template expire
        credit_cost:
          type: integer
          minimum: 1
          default: 1
          description: >-
            Number of credits consumed when a signing request is sent from this
            template. Minimum value is 1.
        settings:
          $ref: '#/components/schemas/SigningRequestSettings'
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/TemplateUser'
          description: Template recipients (included in GET single template)
        fields:
          type: array
          items:
            $ref: '#/components/schemas/TemplateField'
          description: Template fields (included in GET single template)
        created_date:
          type: string
          format: date-time
          description: Template creation timestamp
        updated_date:
          type: string
          format: date-time
          description: Template last update timestamp
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        message:
          type: string
          description: Detailed error description
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    SigningRequestSettings:
      type: object
      description: >-
        Signing request and template settings. All 9 fields are returned by
        every endpoint that includes settings.
      properties:
        allow_download:
          type: boolean
          description: Whether recipients can download the document
          default: true
        attach_pdf_on_finish:
          type: boolean
          description: Whether to attach PDF when signing is complete
          default: true
        allow_editing_before_sending:
          type: boolean
          description: Whether the signing request can be edited before sending
          default: false
        use_signing_order:
          type: boolean
          description: >-
            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.
          default: true
        hand_drawn_only:
          type: boolean
          description: >-
            When enabled, signers can only hand-draw their signatures and cannot
            use typed/font-based signatures
          default: false
        send_signing_email:
          type: boolean
          description: Whether to send signing request notification emails to signers
          default: true
        send_finish_email:
          type: boolean
          description: Whether to send completion email when all signers finish
          default: true
        send_expiration_email:
          type: boolean
          description: Whether to send expiration notification email when request expires
          default: true
        send_cancellation_email:
          type: boolean
          description: >-
            Whether to send cancellation notification email when request is
            cancelled
          default: true
        require_otp_verification:
          type: boolean
          nullable: true
          description: >-
            Whether signers must verify their email with a one-time code before
            accessing the document. null = inherit from workspace/company
            setting.
          default: null
        disable_guided_navigation:
          type: boolean
          nullable: true
          description: >-
            Disable automatic scrolling to the next required field during
            signing. Inherits from workspace or company if not set.
    TemplateUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the template user
        name:
          type: string
          description: Recipient name (combined first and last name)
        email:
          type: string
          format: email
          description: Recipient email address
        first_name:
          type: string
          nullable: true
          description: Recipient first name
        last_name:
          type: string
          nullable: true
          description: Recipient last name
        designation:
          type: string
          enum:
            - Signer
            - Approver
            - CC
          description: >-
            Role of the recipient. Signer signs the document, Approver approves
            with approval fields, CC receives a copy when complete.
        order:
          type: integer
          minimum: 1
          description: Order in which the recipient should sign
        phone_number:
          type: string
          nullable: true
          description: Recipient phone number
        street_address:
          type: string
          nullable: true
          description: Recipient street address
        city:
          type: string
          nullable: true
          description: Recipient city
        state_province:
          type: string
          nullable: true
          description: Recipient state or province
        postal_code:
          type: string
          nullable: true
          description: Recipient postal code
        country:
          type: string
          nullable: true
          description: Recipient country
        title:
          type: string
          nullable: true
          description: Recipient job title
        company:
          type: string
          nullable: true
          description: Recipient company name
        required_fields:
          type: array
          items:
            type: string
          description: >-
            List of recipient data fields required for sending (based on
            template fields with variable_name mappings). Always includes
            'email' and 'first_name'.
        missing_fields:
          type: array
          items:
            type: string
          description: List of required fields that are currently empty for this recipient
        required_read_only_fields:
          type: array
          items:
            type: object
            properties:
              variable_name:
                type: string
                nullable: true
                description: Variable name of the read-only field
              variable_defined_name:
                type: string
                nullable: true
                description: >-
                  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:
                type: string
                description: Type of the field (text, date, etc.)
          description: >-
            List of required read-only fields that need pre-filled values before
            sending
        ready_to_send:
          type: boolean
          description: Whether this recipient has all required data filled in for sending
    TemplateField:
      type: object
      description: A field placed on a template document
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the field
        type:
          type: string
          enum:
            - text
            - signature
            - date
            - checkbox
            - dropdown
            - radio_buttons
            - number
            - text_area
            - file
            - initial
            - stamp
            - approval_signature
            - approval_checkmark
            - approval_date
          description: Type of the field
        required:
          type: boolean
          description: Whether the field is required
        recipient_id:
          type: string
          format: uuid
          nullable: true
          description: ID of assigned recipient
        variable_name:
          type: string
          nullable: true
          description: Variable name for field (used in templates)
        variable_defined_name:
          type: string
          nullable: true
          description: >-
            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:
          type: object
          description: >-
            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.
          properties:
            x:
              type: number
              minimum: 0
              maximum: 100
              description: X coordinate of field position (percentage, 0-100)
            'y':
              type: number
              minimum: 0
              maximum: 100
              description: Y coordinate of field position (percentage, 0-100)
            width:
              type: number
              minimum: 0
              maximum: 100
              description: >-
                Width of the field (percentage, 0-100). Note: x + width must be
                <= 100
            height:
              type: number
              minimum: 0
              maximum: 100
              description: >-
                Height of the field (percentage, 0-100). Note: y + height must
                be <= 100
        page_number:
          type: integer
          minimum: 1
          nullable: true
          description: >-
            Page number where the field is located (1-indexed). Must not exceed
            the document's total page count.
        dropdown_options:
          type: array
          items:
            type: string
          nullable: true
          description: Options for dropdown fields
        multi_group_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            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:
          type: string
          format: date
          nullable: true
          description: >-
            Default date value for date fields (ISO 8601 format, e.g.,
            '2024-01-15')
        date_signing_default:
          type: boolean
          description: Use signing date as default for date fields
        format_rules:
          $ref: '#/components/schemas/DateFormatRules'
          nullable: true
          description: >-
            Formatting rules - currently used for date fields to specify display
            format
        validation_rules:
          $ref: '#/components/schemas/FieldValidationRules'
        read_only:
          type: boolean
          default: false
          description: Whether this field is read-only (pre-filled before signing)
        read_only_value:
          type: string
          nullable: true
          description: Static value for read-only fields
    DateFormatRules:
      type: object
      description: >-
        Formatting rules for date fields. Specifies how date values should be
        displayed and formatted.
      properties:
        dateFormat:
          type: string
          description: >-
            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.
          enum:
            - MM/dd/yyyy
            - dd/MM/yyyy
            - yyyy-MM-dd
            - MMMM dd, yyyy
            - MMM dd, yyyy
            - dd MMMM yyyy
          default: MM/dd/yyyy
      example:
        dateFormat: MMMM dd, yyyy
    FieldValidationRules:
      type: object
      nullable: true
      description: >-
        Validation rules for field values. Reserved for future use - currently
        not enforced for any field types.
      additionalProperties: true
  responses:
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    NotFoundError:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
            message: The requested resource was not found
    RateLimitError:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp of reset
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Use your API key directly without any prefix
        (e.g., 'your-api-key'). Bearer prefix is optional but not required.

````