---
title: "Comprehensive Update Signing Request"
method: PUT
path: "/signing-requests/{id}"
tags: ["Signing Requests"]
---

# Comprehensive Update Signing Request

`PUT /signing-requests/{id}`

Perform comprehensive updates to a signing request including properties, recipients, fields, and reminders. Cannot update after signing request has been sent, completed, or cancelled. All sections are optional but at least one must be provided.

**Temporary ID Pattern for New Recipients**: When adding new recipients in a comprehensive update, use the '_temp_id' field (format: 'temp_X') instead of 'id' to establish relationships with fields and reminders. This allows you to create new recipients and reference them in fields/reminders in a single request. Use the 'id' field to update existing recipients. Validation rules: (1) Temporary IDs must start with 'temp_'; (2) Each temporary ID must be unique within the request; (3) Fields and reminders can reference temporary IDs in their recipient_id property; (4) The API will automatically resolve temporary IDs to real UUIDs after recipient creation.

## Path parameters

- `id` string, uuid, required

## Request body

- UpdateSigningRequestBodySchema
  - `signing_request_properties` object — Update signing request properties
    - `name` string
    - `description` string
    - `document` string, byte — Replace document (base64-encoded PDF)
    - `expiration_hours` integer
    - `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.
    - `completion_title` string, nullable — Heading shown on the completion page after signing. Null or an empty string clears the override.
    - `completion_message` string, nullable — Body text shown on the completion page after signing. Null or an empty string clears the override.
    - `completion_redirect_url` string, uri, nullable — URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Null or an empty string clears the override.
    - `completion_redirect_delay` integer, nullable — Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Null clears the override.
  - `recipients` Recipient[] — Upsert recipients - include 'id' to update existing recipients, use '_temp_id' (e.g., 'temp_1') for new recipients to reference them in fields and reminders within the same request
    - `id` string — Unique identifier. For updates: use existing UUID. For document-based creation: optionally use temporary ID (format: 'temp_1', 'temp_2', etc.) to reference recipients in fields and reminders before creation. Temporary IDs are automatically resolved to real UUIDs in the response.
    - `_temp_id` string — Temporary identifier for new recipients in PUT (comprehensive update) requests (e.g., 'temp_1'). Use this when creating new recipients alongside existing ones in comprehensive updates. Must start with 'temp_' and be unique within the request. Not used for POST (create) requests - use 'id' field instead.
    - `template_user_id` string, uuid — When creating from a template, the ID of the template user to update. If provided, this recipient's data will update the matching template user. If not provided, falls back to matching by order. Only user info (name, email, phone, address, title, company) can be updated - order and designation are always inherited from the template.
    - `first_name` string, required — Recipient's first name
    - `last_name` string — Recipient's last name (optional, but required if using full_name or last_name prefilled variables)
    - `email` string, email, required — Recipient's email address
    - `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 — Signing sequence number. Recipients must sign in order, with lower numbers signing first. This field is required for all recipients.
    - `phone_number` string, nullable — Recipient's phone number
    - `street_address` string, nullable — Street address
    - `city` string, nullable — City
    - `state_province` string, nullable — State or province
    - `postal_code` string, nullable — Postal/ZIP code
    - `country` string, nullable — Country
    - `title` string, nullable — Job title
    - `company` string, nullable — Company name
    - `custom_fields` object — Custom key-value pairs for additional recipient data
  - `deleted_recipients` DeletedRecipient[] — Recipients to delete and how to handle their fields
    - `recipient_id` string, uuid, required — ID of recipient to delete
    - `field_action` 'delete' | 'reassign', required — Action to take with fields assigned to this recipient
    - `reassign_to_recipient_id` string, uuid — Recipient to reassign fields to (required if field_action is 'reassign')
  - `force_remove_conditions` boolean — When deleting recipients 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 listing the dependent fields.
  - `fields` Field[] — Upsert fields - include id to update, omit id to create new
    - `id` string, uuid — Unique identifier (include for updates, omit for new fields)
    - `template_field_id` string, uuid — Template field ID to match for partial updates (template-based creation only). Use this to identify which template field to override. Takes precedence over variable_name for matching.
    - `type` 'signature' | 'text' | 'date' | 'checkbox' | 'dropdown' | 'initial' | 'initials' | 'text_area' | 'textarea' | 'image' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required — Type of field. Accepts 'initial' or 'initials' (normalized to 'initial'), 'textarea' or 'text_area' (normalized to 'text_area').
    - `position` object, required — Field must fit within page bounds: x + width <= 100 and y + height <= 100
      - `x` number, required — X coordinate as percentage (0-100)
      - `y` number, required — Y coordinate as percentage (0-100)
      - `width` number, required — Width as percentage (0-100). x + width must be <= 100
      - `height` number, required — Height as percentage (0-100). y + height must be <= 100
    - `page_number` integer, required — Page number where field is located (1-indexed). Must not exceed the document's total page count.
    - `required` boolean — Whether field must be completed
    - `recipient_id` string — ID of recipient assigned to this field. Use real UUID for template-based creation or updates, or temporary ID (e.g., 'temp_1') for document-based creation to reference recipients defined in the same request.
    - `variable_name` string, nullable — Variable name for field (used in templates). Also used as fallback for field matching in template-based creation when template_field_id is not provided.
    - `variable_defined_name` string, nullable — Human-readable custom field definition name. Can be used as an alternative to variable_name for targeting fields in template-based creation.
    - `dropdown_options` union — Options for dropdown fields
      - string[]
      - object
    - `date_default` string, date, nullable — Default date value
    - `date_signing_default` boolean — Use signing date as default
    - `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.
    - `format_rules` union — Formatting rules for field value. For date fields, use DateFormatRules schema with dateFormat property. For file fields, use FileFormatRules schema with acceptedFileTypes property (image_and_pdf, image, or pdf). For url fields, use { urlDisplayText: string }. Text-bearing fields (text, textarea, email, name, phone, company, title, number, dropdown, url, date) additionally accept an optional fontSize property (integer px, 8-48, clamped) - see TextFormatRules.
      - 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.
      - FileFormatRules — Formatting rules for file upload fields. Specifies which file types signers are allowed to upload.
        - `acceptedFileTypes` 'image_and_pdf' | 'image' | 'pdf' — Accepted file types for upload. 'image_and_pdf' accepts JPG, PNG, and PDF. 'image' accepts JPG and PNG only. 'pdf' accepts PDF only. Files are validated by magic bytes, not just extension. Maximum file size is 10MB.
      - object
    - `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). When true, the signer cannot edit the field value. Useful for displaying contract terms, recipient information, or other fixed data.
    - `read_only_value` string, nullable — Static value for read-only fields. Takes precedence over prefilled_data if both are specified. Only applicable when read_only is true. Example: 'Contract #12345' or 'Acme Corporation'.
    - `prefilled_data` 'first_name' | 'last_name' | 'full_name' | 'email' | 'phone_number' | 'company' | 'title' | 'street_address' | 'city' | 'state_province' | 'postal_code' | 'country', nullable — User attribute to auto-populate when read_only is true. Value is pulled from the assigned recipient's data at signing time. Can also reference custom_fields keys defined on the recipient (not limited to enum values). Only applicable when read_only is true and read_only_value is not set. Example: Set to 'email' to display the recipient's email address.
    - `required_conditions` ConditionSet — A set of condition groups with nested logic. The outer 'logic' operator combines groups, while each group's conditions use the opposite operator. Example: logic='and' means all groups must match, and within each group any condition can match (OR).
      - `logic` 'and' | 'or', required — Logical operator to combine groups. 'and' = all groups must match, 'or' = any group can match.
      - `groups` ConditionGroup[], required — Array of condition groups
        - `conditions` Condition[], required — Array of conditions within this group. Combined using the opposite of the parent ConditionSet's logic operator.
          - `field_id` string, uuid, required — ID of the field to evaluate
          - `operator` 'is_filled' | 'is_empty' | 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal', required — Comparison operator. 'is_filled'/'is_empty' don't require a value. Text operators: equals, not_equals, contains, not_contains. Numeric/date operators: greater_than, less_than, greater_than_or_equal, less_than_or_equal.
          - `value` union — Value to compare against. Not required for is_filled/is_empty operators.
            - string
            - number
    - `visibility_conditions` ConditionSet — A set of condition groups with nested logic. The outer 'logic' operator combines groups, while each group's conditions use the opposite operator. Example: logic='and' means all groups must match, and within each group any condition can match (OR).
      - `logic` 'and' | 'or', required — Logical operator to combine groups. 'and' = all groups must match, 'or' = any group can match.
      - `groups` ConditionGroup[], required — Array of condition groups
        - `conditions` Condition[], required — Array of conditions within this group. Combined using the opposite of the parent ConditionSet's logic operator.
          - `field_id` string, uuid, required — ID of the field to evaluate
          - `operator` 'is_filled' | 'is_empty' | 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal', required — Comparison operator. 'is_filled'/'is_empty' don't require a value. Text operators: equals, not_equals, contains, not_contains. Numeric/date operators: greater_than, less_than, greater_than_or_equal, less_than_or_equal.
          - `value` union — Value to compare against. Not required for is_filled/is_empty operators.
            - string
            - number
    - `background_color` string, nullable — Background color for the field as a hex color string (e.g., '#FFFDE7', '#fff'). Useful for highlighting fields that need attention.
  - `reminders` SigningRequestReminder[] — Upsert reminders - include id to update, omit id to create new
    - `id` string, uuid — Unique identifier (include for updates, omit for new reminders)
    - `hours` integer, required — Hours before expiration to send reminder
    - `all_users` boolean — Send reminder to all recipients
    - `recipient_id` string, nullable — Specific recipient ID (required if all_users is false). Use real UUID for existing recipients or temporary ID (e.g., 'temp_1') for document-based creation to reference recipients in the same request.
    - `subject` string, required — Email subject line
    - `message` string, required — Email message body
  - `language` 'en' | 'es' | 'it' | 'pt' | 'fr' | 'de' | 'el' | 'ru' | 'pl' | 'cs' | 'sv' | 'nl' | 'ro' | 'nb', nullable — Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior).

## Response `200`

Signing request updated successfully. Returns the updated signing request and summary of changes made.

- SigningRequestUpdateResponse — Signing request update result
  - `id` string, uuid, required — Signing request ID (for backward compatibility)
  - `name` string, required — Signing request name (for backward compatibility)
  - `signing_request` object — Summary of the updated signing request (subset of full SigningRequest schema)
    - `id` string, uuid — Signing request ID
    - `name` string — Signing request name
    - `description` string, nullable — Signing request description (mapped from template_description)
    - `document_url` string, uri — Pre-signed URL to the PDF document
    - `document_url_expires_at` string, date-time, nullable — When the document URL expires
    - `document_page_count` integer — Number of pages in the document
    - `status` string — Current status of the signing request
    - `expiration_hours` integer — Hours until signing request expires
    - `settings` object — Subset of signing request settings returned in PUT response
      - `allow_download` boolean — Whether recipients can download the document
      - `attach_pdf_on_finish` boolean — Whether to attach PDF on completion
      - `hand_drawn_only` boolean — Whether only hand-drawn signatures are allowed
    - `template_id` string, uuid, nullable — Template ID if created from a template
    - `expires_at` string, date-time, nullable — ISO 8601 timestamp when the signing request expires
    - `created_date` string, date-time — Creation timestamp
    - `sent_date` string, date-time, nullable — When the signing request was sent
    - `finished_date` string, date-time, nullable — When all signatures were completed
    - `cancelled_date` string, date-time, nullable — When the signing request was cancelled
  - `recipients` Recipient[] — Updated recipients list
    - `id` string — Unique identifier. For updates: use existing UUID. For document-based creation: optionally use temporary ID (format: 'temp_1', 'temp_2', etc.) to reference recipients in fields and reminders before creation. Temporary IDs are automatically resolved to real UUIDs in the response.
    - `_temp_id` string — Temporary identifier for new recipients in PUT (comprehensive update) requests (e.g., 'temp_1'). Use this when creating new recipients alongside existing ones in comprehensive updates. Must start with 'temp_' and be unique within the request. Not used for POST (create) requests - use 'id' field instead.
    - `template_user_id` string, uuid — When creating from a template, the ID of the template user to update. If provided, this recipient's data will update the matching template user. If not provided, falls back to matching by order. Only user info (name, email, phone, address, title, company) can be updated - order and designation are always inherited from the template.
    - `first_name` string, required — Recipient's first name
    - `last_name` string — Recipient's last name (optional, but required if using full_name or last_name prefilled variables)
    - `email` string, email, required — Recipient's email address
    - `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 — Signing sequence number. Recipients must sign in order, with lower numbers signing first. This field is required for all recipients.
    - `phone_number` string, nullable — Recipient's phone number
    - `street_address` string, nullable — Street address
    - `city` string, nullable — City
    - `state_province` string, nullable — State or province
    - `postal_code` string, nullable — Postal/ZIP code
    - `country` string, nullable — Country
    - `title` string, nullable — Job title
    - `company` string, nullable — Company name
    - `custom_fields` object — Custom key-value pairs for additional recipient data
  - `reminders` Reminder[] — Updated reminders list
    - `id` string, uuid, required — Unique identifier for the reminder
    - `hours` integer, required — Hours after sending before reminder is sent
    - `subject` string, required — Email subject for the reminder
    - `message` string, required — Email message body for the reminder
    - `all_users` boolean — Whether reminder applies to all users
    - `template_user_id` string, uuid, nullable — Specific user to send reminder to (used in template context)
    - `recipient_id` string, uuid, nullable — Specific recipient to send reminder to (used in signing request context, same as template_user_id)
    - `sent_on` string, date-time, nullable — Timestamp when the reminder was actually sent
    - `created_at` string, date-time — Reminder creation timestamp
    - `updated_at` string, date-time — Reminder last update timestamp
  - `summary` object — Summary of all changes made in this update
    - `properties_updated` boolean — Whether any properties were updated
    - `recipients_created` integer — Number of new recipients created
    - `recipients_updated` integer — Number of existing recipients updated
    - `recipients_deleted` integer — Number of recipients soft-deleted
    - `fields_created` integer — Number of new fields created
    - `fields_updated` integer — Number of existing fields updated
    - `fields_reassigned` integer — Number of fields reassigned to another recipient
    - `fields_deleted` integer — Number of fields soft-deleted
    - `reminders_created` integer — Number of new reminders created
    - `reminders_updated` integer — Number of existing reminders updated
    - `warnings` string[] — Email format warnings for recipients (non-blocking)

## Other responses

- `400` — Validation errors. All section errors returned together.
- `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)