FIfirma
Templates

Replace template document

Changed on

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.

post/templates/{id}/replace-document

Request

Path parameters

idstring uuid required

Template ID

Request body

documentstring 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_idstring uuid

ID of a previously uploaded document (mutually exclusive with document). Obtain by calling POST /documents first.

Example request

{
  "document_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

Document replaced successfully

idstring uuid required

Unique identifier for the template

namestring required

Template name

descriptionstring nullable

Template description

document_urlstring 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_atstring 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_countinteger

Number of pages in the document

expiration_hoursinteger

Hours until signing requests created from this template expire

credit_costinteger

Number of credits consumed when a signing request is sent from this template. Minimum value is 1.

created_datestring date-time required

Template creation timestamp

updated_datestring date-time

Template last update timestamp

documents_versioninteger

Version of the document set, raised by every document change (multi-document; available to every company). While multi-document editing is suspended, this key is absent on the single-document path and in list and create responses.

documents_layout_versioninteger

Version of the document layout, raised when documents are added, removed or reordered (multi-document; available to every company). Field writes on a signing request with more than one document send it back as documents_layout_version. While multi-document editing is suspended, this key is absent on the single-document path and in list and create responses.

Example response

{
  "fields": [
    {
      "format_rules": {
        "dateFormat": "MMMM dd, yyyy"
      }
    }
  ],
  "documents": [
    {
      "document_id": null,
      "position": 1,
      "label": null,
      "original_filename": null,
      "page_count": 3,
      "document_url": "https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example",
      "document_url_kind": "stored",
      "document_only_hash": null
    }
  ]
}

Changes

  • a6525941bc28Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added to the response body anyOf list for the response status

  • 3a2cdde3a64fRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status