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

# Partially Update Signing Request

`PATCH /signing-requests/{id}`

Update signing request properties, a single recipient, OR a single field. Cannot update multiple entity types in one request. Cannot update after signing request has been sent, completed, or cancelled.

## Path parameters

- `id` string, uuid, required

## Request body

- union
  - object — Update signing request properties only
    - `name` string — New name for signing request
    - `description` string — New description
    - `document` string, byte — Replace document with new base64-encoded PDF. Page count will be auto-extracted.
    - `expiration_hours` integer — New expiration hours
    - `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.
    - `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).
    - `completion_title` string, nullable — Heading shown on the completion page after signing. Null or an empty string clears the override; omitted leaves it unchanged.
    - `completion_message` string, nullable — Body text shown on the completion page after signing. Null or an empty string clears the override; omitted leaves it unchanged.
    - `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; omitted leaves it unchanged.
    - `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; omitted leaves it unchanged.
  - object — Create or update a single recipient
    - `recipient` Recipient, required — Recipient schema with auto-construction and mapping behaviors. **Name field**: Auto-constructed from first_name and last_name ('First Last' if both present, otherwise 'First'). Manual name values are overwritten. **Order assignment**: ALL recipients MUST have an explicit order value. Order determines the signing sequence, which is always enforced. Recipients must sign in order, with lower numbers signing first. **Custom fields**: Supports both flat structure (e.g., company_name at root) and nested structure (custom_fields object). Both formats are normalized internally. **Template field mapping**: When creating from a template with custom recipients, use template_user_id or order to match template users. Only user info (name, email, phone, etc.) can be updated - order and designation are inherited from template. **Temporary IDs**: For document-based creation, use temporary IDs (format: 'temp_1', 'temp_2', etc.) to reference recipients in fields and reminders before they're created. **CC recipients**: CC recipients receive a completed copy but cannot sign or have fields assigned. At least one Signer is required.
      - `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
  - object — Create or update a single field
    - `field` object, required
      - `id` string, uuid — Include to update existing field, omit to create new
      - `type` 'text' | 'signature' | 'date' | 'checkbox' | 'initial' | 'initials' | 'dropdown' | 'radio_buttons' | 'textarea' | 'text_area' | 'url' | 'file' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date' — Field type. Accepts 'initial' or 'initials', 'textarea' or 'text_area'. Required for new fields. url fields are automatically read-only. file fields allow signers to upload attachments (images/PDF). stamp fields display a pre-configured image.
      - `position` object — Position object. All properties required for new fields.
        - `x` number — X position on document
        - `y` number — Y position on document
        - `width` number — Field width
        - `height` number — Field height
      - `page_number` integer — Page number (1-indexed). Required for new fields.
      - `required` boolean — Whether field is required
      - `recipient_id` string, uuid, nullable — Recipient ID to assign field to
      - `variable_name` string — Variable name for prefilled data mapping
      - `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
      - `format_rules` object — Format rules (e.g., date format, urlDisplayText for url fields, acceptedFileTypes for file fields)
      - `validation_rules` object — Validation rules for the field
      - `multi_group_id` string, uuid — Group ID for radio button groups
      - `date_default` string — Default date value
      - `date_signing_default` boolean — For date fields, use signing date as default
      - `read_only` boolean — Whether field is read-only (automatically true for url fields)
      - `read_only_value` string — Static value for read-only fields. For url fields, this is the URL to link to.
      - `final_value` string — Final value of the field (for pre-filled read-only fields)

## Response `200`

Signing request updated successfully. Response shape depends on what was updated: properties update returns {id, name, template_description, document_url, expiration_hours}; recipient update returns the full recipient object; field update returns the full field object. Response may include a 'warning' field for email format validation warnings (non-blocking).

- union
  - object — Response when updating properties
    - `id` string, uuid
    - `name` string
    - `template_description` string, nullable
    - `document_url` string, uri
    - `expiration_hours` integer
  - object — Response when updating/creating a recipient
  - object — Response when updating/creating a field

## Other responses

- `400` — Bad Request - Cannot update both properties and recipient in same request, or signing request already sent/completed/cancelled
- `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)