FIfirma
Templates

Comprehensive Template Update

Changed on

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.

Not atomic. The parts of this call are not applied as one update. Each entry of users or deleted_users that adds, moves or removes a signer or an approver is saved on its own, in the order of the request. If one of these saves is refused, the call answers at once with that error: what was saved before it stays applied and the rest of the request is not processed. Other problems (for example a user that is not found, or an invalid field or reminder) are collected and answered as one 400 VALIDATION_ERROR at the end of the call. Once a problem was collected, some of the remaining changes are skipped (the users, fields and reminders entries that follow it) and others can still be applied before the 400, and what was saved before the problem stays applied. The 400 does not always say which entries failed. Read the template again after any non-2xx response. If the read of the template's seal participants for the response fails after the writes, the call answers 500 although the writes were applied.

Seal participants. The request property seal_participants sets the seal participants of the template. When the key is absent, the seal participants of the template are left unchanged. When it is an array, the array replaces the whole set: every seal participant the template had is removed together with the fields it owned, and one seal participant is created for each entry, so [] removes them all. Each entry is an object with seal_id (required, the ID of an organization seal), order (required, a positive integer that no other entry repeats and that is not greater than the number of recipients of the template plus the number of entries) and an optional temp_id. The recipients keep their relative order and each seal is placed at its order. null, any other value that is not an array and an entry without seal_id answer 400 VALIDATION_ERROR; an order that breaks the rules above answers 400 INVALID_SIGNING_ORDER; a seal_id that is not a UUID answers 404 NOT_FOUND; a seal of your company that is revoked or deleted answers 400 SEAL_UNAVAILABLE. Each of these answers is immediate and leaves the seal participants unchanged. seal_participants is processed after the other parts of the call, also when they collected problems, so it can be applied in a call that then answers 400 VALIDATION_ERROR.

put/templates/{id}

Request

Path parameters

idstring uuid required

Request body

force_remove_conditionsboolean

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.

documents_layout_versioninteger

The documents_layout_version of your last read (multi-document). Required for a field write on a template with more than one document or a layout version above 1 (409 DOCUMENTS_LAYOUT_VERSION_REQUIRED); a stale value answers 409 DOCUMENT_SET_VERSION_CONFLICT; a value that is not a non-negative integer answers 400 VALIDATION_ERROR with key documents_layout_version.

Example request

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

Response

Template updated successfully. Returns full template with all relationships. seal_participants lists only the seal participants whose seal belongs to the company of the API key: a seal participant whose seal is missing or belongs to another company is omitted, so an empty or shorter list does not prove that the template has no other seal participant stored.

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 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