FIfirma
Templates

Create Template

Changed on

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

seal_participants, recipients and fields are not accepted keys on this operation: they are ignored and nothing is created from them. When the request body contains any of them (the key being present is enough, whatever its value, including null or []), the 201 response carries warnings, one string per ignored key. Add participants and fields with PATCH /templates/{id} or PUT /templates/{id}.

post/templates

Request

Request body

namestring required

Template name

descriptionstring

Template description

documentstring byte

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 and document_ids)

expiration_hoursinteger

Hours until signing request expires

document_idstring uuid

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

document_idsstring[]

Temporary upload ids from POST /documents, in document order, to create a multi-document template (available to every company). Exactly one of document, document_id or document_ids (400 CONFLICTING_DOCUMENT_SOURCE); a repeated id answers 400 DUPLICATE_DOCUMENT_ID, more than 20 400 MAX_DOCUMENTS_EXCEEDED, an unknown or expired upload 400 DOCUMENT_UPLOAD_NOT_FOUND, a set above 100 MB 413 DOCUMENT_SET_TOO_LARGE. While multi-document editing is suspended, more than one entry in document_ids answers 409 MULTI_DOCUMENT_READ_ONLY.

Example request

{
  "name": "Employment Contract Template",
  "description": "Standard employment contract for new hires",
  "document": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...",
  "expiration_hours": 168,
  "document_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

Template created 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.

warningsstring[]

Present only when the request body contained seal_participants, recipients or fields (the key being present is enough, whatever its value, including null or []). One string per such key, in the order seal_participants, recipients, fields.

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
    }
  ],
  "warnings": [
    "seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}"
  ]
}

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 new optional request property /

    • info

      added the new optional request property /

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status