---
title: "Create Signing Request"
method: POST
path: "/signing-requests"
tags: ["Signing Requests"]
---

# Create Signing Request

`POST /signing-requests`

Create a new signing request either from a PDF document (document-based) or from an existing template (template-based). For document-based creation, allow_editing_before_sending is automatically set to true. For template-based creation, properties are inherited from the template and can be overridden.

**Temporary ID Pattern**: For document-based creation, you can reference recipients before they're created using temporary IDs (format: 'temp_X' where X is any identifier, e.g., 'temp_1', 'temp_alice'). Use these temporary IDs in recipient.id, field.recipient_id, and reminder.recipient_id. The API validates all references and automatically maps temporary IDs to real UUIDs after recipients are created. The response contains only real UUIDs.

**Temporary ID Validation**: Temporary IDs must start with 'temp_', be unique across all recipients in the request, and all field/reminder references must point to recipients defined in the same request. Invalid format, duplicate IDs, or missing recipient references return a 400 error with detailed validation messages.

## Request body

- union
  - object — Create signing request from a PDF document
    - `document` string, byte, required — Base64-encoded PDF or DOCX document. DOCX files are automatically converted to PDF. Page count will be auto-extracted. For documents larger than 5 MB, use POST /documents and pass the document_id instead.
    - `name` string — Name for the signing request
    - `description` string — Description for the signing request
    - `expiration_hours` integer — Hours until the signing request expires (default: 168 = 7 days)
    - `recipients` Recipient[] — Recipients for the signing request. Use temporary IDs (e.g., 'temp_1') in the id field to reference recipients in fields/reminders.
      - `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
    - `fields` Field[] — Fields to place on the document. Use recipient_id to assign fields to recipients.
      - `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.
              - …
      - `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.
              - …
      - `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.
    - `anchor_tags` AnchorTag[] — Anchor tags for automatic field placement. Text markers in the PDF are located and converted to positioned fields. The anchor text is removed from the PDF after processing. Fields created from anchor tags are added alongside any manually specified fields. Only available for document-based creation (not template-based).
      - `anchor_string` string, required — Text string to search for in the PDF document. Common patterns include '{{SIGN_HERE}}', '{{DATE}}', etc.
      - `type` 'signature' | 'initial' | 'initials' | 'text' | 'date' | 'checkbox' | 'radio_buttons' | 'radio' | 'dropdown' | 'textarea' | 'text_area' | 'url' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required — Type of field to place at the anchor location
      - `recipient_id` union, required — ID of the recipient assigned to this field. Use temporary ID (e.g., 'temp_1') for document-based creation or integer order for template-based.
        - integer
        - string
      - `x_offset` number — Horizontal offset from anchor position. Units determined by offset_units (default: percent of page width).
      - `y_offset` number — Vertical offset from anchor position. Units determined by offset_units (default: percent of page height).
      - `offset_units` 'percent' | 'pixels' — Unit type for x_offset and y_offset. 'percent' = percentage of page dimensions, 'pixels' = PDF points (72 DPI).
      - `width` number — Field width as percentage of page width. Defaults vary by field type (e.g., signature=25, text=20, checkbox=3).
      - `height` number — Field height as percentage of page height. Defaults vary by field type (e.g., signature=5, text=3, checkbox=3).
      - `case_sensitive` boolean — Whether anchor string matching is case-sensitive
      - `match_whole_word` boolean — Whether to match whole words only (bounded by non-word characters)
      - `ignore_if_not_present` boolean — If true, skip this anchor without error when not found in the document. If false (default), a missing anchor causes a validation error.
      - `occurrence` integer — Which occurrence to place a field on. 0 = all occurrences (default), 1 = first only, 2 = second only, etc.
      - `remove_anchor_text` boolean — Whether to remove the anchor text using corrected glyph geometry and sub-pixel text removal. Defaults to true.
      - `add_white_background` boolean — Whether to draw a white background across the full resolved field rectangle. This is independent of anchor-text removal.
      - `required` boolean — Whether the field must be completed by the signer
      - `read_only` boolean — Whether the field is read-only (pre-filled)
      - `read_only_value` string, nullable — Static value for read-only fields
      - `variable_name` string, nullable — Variable name for the field
      - `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.
      - `background_color` string, nullable — Background color as hex (e.g., '#FFFDE7')
      - `font_size` integer — Optional starting/maximum font size in pixels for text-bearing field types, stored on the resolved field as format_rules.fontSize (see TextFormatRules). Text still auto-shrinks to fit the field box. Omit for automatic sizing. Values outside 8-48 are clamped; non-numeric values are ignored.
      - `dropdown_options` union — Options for dropdown fields
        - string[]
        - object
      - `date_default` string, nullable — Default date value
      - `date_signing_default` boolean — Use signing date as default
      - `multi_group_id` string, nullable — Group ID for linking checkbox/radio fields
    - `reminders` SigningRequestReminder[] — Reminders to send to recipients
      - `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
    - `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. Inherits from the workspace, then the company, when omitted or null.
    - `completion_message` string, nullable — Body text shown on the completion page after signing. Inherits from the workspace, then the company, when omitted or null.
    - `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). Inherits from the workspace, then the company, when omitted or null.
    - `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. Inherits from the workspace, then the company, when omitted or null.
  - object — Create signing request from a template. Supports partial updates for both recipients and fields.
    - `template_id` string, uuid, required — ID of the template to create signing request from. The document, fields, and default recipients will be copied from the template.
    - `name` string — Custom name for signing request (defaults to template name if not provided)
    - `description` string — Custom description (defaults to template description if not provided)
    - `expiration_hours` integer — Override template expiration hours
    - `recipients` Recipient[] — Optional recipient overrides. Use template_user_id (preferred) or order (fallback) to match template users. Only user info (first_name, last_name, email, phone_number, address fields, title, company) can be updated - order and designation are always inherited from template. Recipients not provided will use template defaults.
      - `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
    - `fields` Field[] — Optional field overrides for partial updates. Use template_field_id (preferred) or variable_name (fallback) to match template fields. Only provided properties override template defaults. Supported override properties: type, required, position, read_only, read_only_value, format_rules, validation_rules, dropdown_options, date_default, date_signing_default, multi_group_id. Fields not matched are ignored. If fields array is omitted, all template fields are used as-is.
      - `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.
              - …
      - `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.
              - …
      - `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.
    - `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. Falls back to the template value, then the workspace and company defaults, when omitted or null.
    - `completion_message` string, nullable — Body text shown on the completion page after signing. Falls back to the template value, then the workspace and company defaults, when omitted or null.
    - `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). Falls back to the template value, then the workspace and company defaults, when omitted or null.
    - `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. Falls back to the template value, then the workspace and company defaults, when omitted or null.

## Response `201`

Signing request created successfully. The response may include non-blocking email or anchor-tag warnings.

- SigningRequestCreateResponse — Signing request as returned by CREATE endpoints (POST /signing-requests)
  - `id` string, uuid, required — Unique identifier for the signing request
  - `name` string, required — Signing request name
  - `description` string, nullable — Signing request description
  - `status` 'draft', required — Status is always 'draft' for newly created signing requests
  - `document_url` string, uri — Pre-signed URL to the PDF document
  - `page_count` integer — Number of pages in the document
  - `expiration_hours` integer — Hours until signing request expires (default: 168 = 7 days)
  - `template_id` string, uuid, nullable — Template ID if created from a template
  - `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.
  - `created_date` string, date-time — Creation timestamp
  - `updated_date` string, date-time — Last update 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` SigningRequestCreateRecipient[] — Signing request recipients
    - `id` string, uuid — Unique identifier for the recipient
    - `first_name` string, nullable, required — Recipient first name
    - `last_name` string, nullable — Recipient last name
    - `name` string, nullable — Combined full name (auto-constructed from first_name + last_name)
    - `email` string, email, required — Recipient 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 order
    - `phone_number` string, nullable — Recipient phone number
    - `street_address` string, nullable — Street address
    - `city` string, nullable — City
    - `state_province` string, nullable — State or province
    - `postal_code` string, nullable — Postal code
    - `country` string, nullable — Country
    - `title` string, nullable — Job title
    - `company` string, nullable — Company name
    - `custom_fields` object, nullable — Custom key-value pairs
    - `finished_date` string, date-time, nullable — When this recipient completed signing
  - `fields` SigningRequestCreateField[] — Signing request fields with flat position values
    - `id` string, uuid — Unique identifier for the field
    - `type` 'text' | 'signature' | 'date' | 'checkbox' | 'dropdown' | 'radio_buttons' | 'number' | 'text_area' | 'file' | 'initial' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required — Type of the field
    - `recipient_id` string, uuid, nullable, required — ID of assigned recipient
    - `page_number` integer, required — Page number (1-indexed)
    - `x_position` number — X coordinate as percentage (0-100)
    - `y_position` number — Y coordinate as percentage (0-100)
    - `width` number — Width as percentage (0-100)
    - `height` number — Height as percentage (0-100)
    - `required` boolean — Whether the field is required
    - `read_only` boolean — Whether this field is read-only
    - `read_only_value` string, nullable — Static value for read-only fields
    - `variable_name` string, nullable — Variable name for prefilled data mapping
    - `variable_defined_name` string, nullable — Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise.
    - `dropdown_options` union — Options for dropdown fields
      - string[]
      - object
    - `format_rules` object, nullable — Formatting rules (e.g., date format)
    - `validation_rules` object, nullable — Validation rules for the field
    - `date_signing_default` boolean — Whether to use signing date as default
    - `final_value` string, nullable — Pre-filled or final value of the field
  - `warnings` string[] — Optional non-blocking warnings, including unusual recipient email formats, unknown anchor-tag properties during the compatibility window, and anchor-processing warnings.

## Other responses

- `400` — Bad Request - Validation failed
- `401` — Unauthorized - Invalid or missing API key
- `404` — Template not found or does not belong to workspace
- `429` — Too Many Requests - Rate limit exceeded
- `503` — Anchor-tag processing is disabled on the edge fallback. Retry through the primary API route.

---

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