---
title: "Create and Send Signing Request (Atomic)"
method: POST
path: "/signing-requests/create-and-send"
tags: ["Signing Requests"]
---

# Create and Send Signing Request (Atomic)

`POST /signing-requests/create-and-send`

Create and immediately send a signing request in a single atomic operation. This endpoint combines the functionality of POST /signing-requests and POST /signing-requests/{id}/send.

**Key Benefits:**
- Single API call instead of two separate requests
- Validates all send requirements BEFORE creating the signing request
- Atomic credit deduction - only charges if everything succeeds
- Returns status: 'sent' immediately with first signer details
- More efficient (saves 1 API call + round-trip time)

**Validation:**
- All standard creation validations (document/template, recipients, fields)
- Additional send validations:
  - All signers must have first_name and valid email
  - Required read-only fields must have final_value populated
  - Prefilled data fields (variable_name) must have corresponding user data
  - Company must have sufficient credits (≥1)

**Atomicity:**
- If any validation fails, nothing is created
- Credit is only deducted after successful creation and before email send
- If email send fails after creation, signing request remains in 'draft' status and credit is NOT deducted

**Temporary ID Pattern:** For document-based creation, use temporary IDs (format: 'temp_X') to reference recipients before creation. The API validates all references and automatically maps temporary IDs to real UUIDs.

**Rate Limit:** 120 requests/minute (same as write operations)

## Request body

- union
  - object
    - `name` string, required — Signing request name
    - `description` string — Signing request description
    - `document` string, byte, required — Base64-encoded PDF or DOCX document (mutually exclusive with template_id and document_id). DOCX files are automatically converted to PDF. For documents larger than 5 MB, use POST /documents and pass the document_id instead.
    - `template_id` string, uuid — Template ID to use (mutually exclusive with document and document_id)
    - `expiration_hours` integer — Hours until signing request expires (default: 168 = 7 days)
    - `recipients` Recipient[] — Array of recipients. At least one must be a Signer. For document-based: required. For template-based: optional (uses template recipients if omitted). Use template_user_id (preferred) or order (fallback) to match template users.
      - `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` object[] — Array of fields to be filled (document-based only)
      - `recipient_id` string — Temporary ID or UUID of recipient assigned to this field
      - `type` 'signature' | 'initial' | 'text' | 'date' | 'checkbox' | 'dropdown' | 'radio_buttons' | 'text_area' | 'url' | 'file' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required — Field type. Accepts aliases: "initials" (normalized to "initial"), "textarea" (normalized to "text_area"), "radio" (normalized to "radio_buttons").
      - `page` integer, required — PDF page number (1-indexed)
      - `x` number, required — X coordinate on page
      - `y` number, required — Y coordinate on page
      - `width` number
      - `height` number
      - `variable_name` 'first_name' | 'last_name' | 'full_name' | 'email' | 'phone_number' | 'street_address' | 'city' | 'state_province' | 'postal_code' | 'country' | 'title' | 'company' — Variable name for prefilled data (e.g., 'phone_number', 'company'). If set, the corresponding recipient field must be populated.
      - `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.
      - `required` boolean — Whether field is required
      - `read_only` boolean — Whether field is read-only (pre-filled)
      - `final_value` string — Pre-filled value for read-only fields (required if read_only=true and required=true)
      - `background_color` string, nullable — Background color as hex (e.g., '#FFFDE7')
      - `dropdown_options` union — Options for dropdown fields. Required when type is "dropdown".
        - string[]
        - object
    - `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` object[] — Array of reminder configurations
      - `hours_before_expiration` integer, required — Hours before expiration to send reminder
    - `settings` object — Signing request settings
      - `use_signing_order` boolean — Enforce signing order based on recipient.order. When false, all signers receive the document simultaneously.
      - `allow_download` boolean — Allow recipients to download document
      - `attach_pdf_on_finish` boolean — Attach completed PDF to completion email
      - `send_signing_email` boolean — Send email notification to signers
      - `send_finish_email` boolean — Send email when all signatures complete
      - `send_expiration_email` boolean — Send email when request expires
      - `send_cancellation_email` boolean — Send email when request is cancelled
      - `hand_drawn_only` boolean — Require signers to hand-draw their signatures instead of using typed signatures
      - `identity_editable_fields` string[], nullable — Identity fields signers can edit before signing. null = disabled. When set, a confirmation dialog appears allowing signers to edit the specified fields.
      - `notify_identity_change_webhook` boolean — Send webhook event when a signer changes their identity
      - `notify_identity_change_email` boolean — Send email notification when a signer changes their identity
    - `document_id` string, uuid — ID of a previously uploaded document (mutually exclusive with document and template_id). Obtain by calling POST /documents first.
    - `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 (when template_id is used), then the workspace and company defaults.
    - `completion_message` string, nullable — Body text shown on the completion page after signing. Falls back to the template value (when template_id is used), then the workspace and company defaults.
    - `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 (when template_id is used), then the workspace and company defaults.
    - `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 (when template_id is used), then the workspace and company defaults.
  - object
    - `name` string, required — Signing request name
    - `description` string — Signing request description
    - `document` string, byte — Base64-encoded PDF or DOCX document (mutually exclusive with template_id and document_id). DOCX files are automatically converted to PDF. For documents larger than 5 MB, use POST /documents and pass the document_id instead.
    - `template_id` string, uuid, required — Template ID to use (mutually exclusive with document and document_id)
    - `expiration_hours` integer — Hours until signing request expires (default: 168 = 7 days)
    - `recipients` Recipient[] — Array of recipients. At least one must be a Signer. For document-based: required. For template-based: optional (uses template recipients if omitted). Use template_user_id (preferred) or order (fallback) to match template users.
      - `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` object[] — Array of fields to be filled (document-based only)
      - `recipient_id` string — Temporary ID or UUID of recipient assigned to this field
      - `type` 'signature' | 'initial' | 'text' | 'date' | 'checkbox' | 'dropdown' | 'radio_buttons' | 'text_area' | 'url' | 'file' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date', required — Field type. Accepts aliases: "initials" (normalized to "initial"), "textarea" (normalized to "text_area"), "radio" (normalized to "radio_buttons").
      - `page` integer, required — PDF page number (1-indexed)
      - `x` number, required — X coordinate on page
      - `y` number, required — Y coordinate on page
      - `width` number
      - `height` number
      - `variable_name` 'first_name' | 'last_name' | 'full_name' | 'email' | 'phone_number' | 'street_address' | 'city' | 'state_province' | 'postal_code' | 'country' | 'title' | 'company' — Variable name for prefilled data (e.g., 'phone_number', 'company'). If set, the corresponding recipient field must be populated.
      - `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.
      - `required` boolean — Whether field is required
      - `read_only` boolean — Whether field is read-only (pre-filled)
      - `final_value` string — Pre-filled value for read-only fields (required if read_only=true and required=true)
      - `background_color` string, nullable — Background color as hex (e.g., '#FFFDE7')
      - `dropdown_options` union — Options for dropdown fields. Required when type is "dropdown".
        - string[]
        - object
    - `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` object[] — Array of reminder configurations
      - `hours_before_expiration` integer, required — Hours before expiration to send reminder
    - `settings` object — Signing request settings
      - `use_signing_order` boolean — Enforce signing order based on recipient.order. When false, all signers receive the document simultaneously.
      - `allow_download` boolean — Allow recipients to download document
      - `attach_pdf_on_finish` boolean — Attach completed PDF to completion email
      - `send_signing_email` boolean — Send email notification to signers
      - `send_finish_email` boolean — Send email when all signatures complete
      - `send_expiration_email` boolean — Send email when request expires
      - `send_cancellation_email` boolean — Send email when request is cancelled
      - `hand_drawn_only` boolean — Require signers to hand-draw their signatures instead of using typed signatures
      - `identity_editable_fields` string[], nullable — Identity fields signers can edit before signing. null = disabled. When set, a confirmation dialog appears allowing signers to edit the specified fields.
      - `notify_identity_change_webhook` boolean — Send webhook event when a signer changes their identity
      - `notify_identity_change_email` boolean — Send email notification when a signer changes their identity
    - `document_id` string, uuid — ID of a previously uploaded document (mutually exclusive with document and template_id). Obtain by calling POST /documents first.
    - `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 (when template_id is used), then the workspace and company defaults.
    - `completion_message` string, nullable — Body text shown on the completion page after signing. Falls back to the template value (when template_id is used), then the workspace and company defaults.
    - `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 (when template_id is used), then the workspace and company defaults.
    - `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 (when template_id is used), then the workspace and company defaults.

## Response `201`

Signing request created and sent successfully. The response may include non-blocking anchor-tag warnings.

- CreateAndSendResponse — Signing request created and sent
  - `id` string, uuid, required — Signing request ID
  - `name` string, required — Signing request name
  - `description` string, nullable — Signing request description
  - `status` 'sent', required — Always 'sent' for this endpoint
  - `document_url` string, uri — Signed URL to access document
  - `page_count` integer — Number of pages in document
  - `expiration_hours` integer — Hours until expiration
  - `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
  - `sent_date` string, date-time — When request was sent
  - `template_id` string, uuid, nullable
  - `first_signer` object — Details of the first signer who received the email
    - `id` string, uuid
    - `name` string
    - `email` string, email
    - `signing_link` string, uri — Direct link for signer to access signing view
  - `recipients` object[] — All recipients with real UUIDs
    - `id` string, uuid
    - `first_name` string
    - `last_name` string, nullable
    - `name` string
    - `email` string, email
    - `designation` string
    - `order` integer
  - `fields` Field[] — All fields with real recipient UUIDs
    - `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.
  - `credits_remaining` integer — Company credits remaining after deduction
  - `warnings` string[] — Optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

## Other responses

- `400` — Validation error - invalid input or missing required signer data
- `401` — Unauthorized - Invalid or missing API key
- `402` — Insufficient credits
- `404` — Template not found or does not belong to workspace
- `422` — Recipient email address is suppressed (previously bounced or marked as spam) and cannot be sent to
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Unexpected server error. Any partially-created signing request is rolled back, so no draft is left behind. Client-actionable send-step failures return 400, 402, or 422 instead.
- `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)