> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Partially Update Signing Request

> 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, except for a seal swap (see `seal_participant`). A `seal_participant` that names a seal answers 404 `NOT_FOUND` when the seal does not exist or belongs to another company, and 400 `SEAL_UNAVAILABLE` when the seal is revoked, deleted or not the current version of its lineage, and also when it is limited to a workspace other than the signing request's. These answers are for adding a seal participant and for changing its seal. A seal swap (`swap_to_seal_id`) answers differently for the new seal: 404 `NOT_FOUND` when it does not exist, belongs to another company or is limited to a workspace other than the signing request's; 409 `SEAL_UNAVAILABLE` when it is revoked, deleted or not the current version of its lineage; 400 `SEAL_FIELD_REQUIRED` when the seal participant has no stamp field on the signing request. Adding a seal participant or changing its seal answers 503 `SEALS_DISABLED` when organization seals are not enabled. Adding a seal participant requires `order` (see the order contract). A field that belongs to a seal participant accepts only `position` and `page_number` changes; every other key of `field`, `recipient_id` included, is ignored.



## OpenAPI

````yaml api-reference/v01.39.01/openapi-v01.39.01.json patch /signing-requests/{id}
openapi: 3.0.3
info:
  title: Firma Partner API
  description: >-
    RESTful API for document signing and template management.


    **Authentication**: All endpoints require API key authentication via the
    `Authorization` header. Use your API key directly without any prefix (e.g.,
    `your-api-key`). The Bearer prefix is optional but not required.


    **Security Features**:

    - Input validation using Zod schemas with detailed field-level error
    messages

    - RSA-256 signed JWT tokens for embedded template access


    **Rate Limiting**: Rate limits are tiered based on operation type:

    - Read operations (GET): 200 requests per minute

    - Write operations (POST/PUT/PATCH/DELETE): 120 requests per minute

    - Webhook CRUD operations: 60 requests per minute

    - Webhook test: 10 requests per minute

    - API key regeneration/expiration: 1 request per minute

    - Webhook secret rotation: 1 request per minute


    When rate limits are exceeded, the API returns a `429 Too Many Requests`
    response with headers:

    - `X-RateLimit-Limit`: Maximum requests per minute for this endpoint

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets

    - `Retry-After`: Seconds until retry is allowed


    **Error Handling**: All errors return structured JSON responses with `error`
    (human-readable message), `code` (machine-readable identifier), and
    `details` (field-level validation errors when applicable).


    **Embedded Template Integration**: The Firma Template Editor can be embedded
    in your application using a standalone JavaScript library.


    ```html

    <!-- Load the Firma Template Editor library -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Generate JWT token via API first

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Initialize editor with JWT token
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    ```


    **X-Firma-Deprecation Header**: Some seal creation and image update
    operations return an `X-Firma-Deprecation` response header when called on
    the edge gateway, indicating the operation should be performed on the
    primary API host instead.


    **Multi-document documents (API 01.39.00, enablement required)**: a template
    or signing request can hold up to 20 documents. The `/documents`
    sub-resource routes and the `documents`, `documents_version` and
    `documents_layout_version` keys are served only for companies enabled for
    multi-document documents; for any other company the routes answer `404
    NOT_FOUND` and the keys are absent.


    **Template seals on create (API 01.39.01)**: creating a signing request from
    a template with `POST /signing-requests` or `POST
    /signing-requests/create-and-send` now inherits the template's seal
    participants, and the template fields that belong to them, when
    `seal_participants` is absent or `null`. This changes the behaviour of v1
    without a version bump; send `seal_participants: []` to create the request
    with no seals. `POST /templates/{id}/duplicate` also carries the template's
    seal participants over; see that operation for how it differs for companies
    enabled for multi-document documents. `GET /templates/{id}` returns
    `seal_participants`, and `POST /templates` answers `warnings` when its body
    contains keys it ignores.
  version: 01.39.01
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: Production API - Recommended (Current)
  - url: https://api.firma.dev/api/v1
    description: Production API - Planned
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Company information and settings
  - name: Workspaces
    description: Workspace management operations
  - name: Templates
    description: Template management operations
  - name: Signing Requests
    description: Document signing request operations
  - name: Custom Fields
    description: >-
      Custom field definition management for workspaces, templates, and signing
      requests
  - name: Webhooks
    description: Webhook configuration and management
  - name: JWT Management
    description: JWT token generation and revocation for embedded templates
  - name: Workspace Settings
    description: Workspace configuration and settings
  - name: Email Domains
    description: >-
      Email domain setup and verification for sending signing request emails
      from custom domains
  - name: Email Templates
    description: >-
      Email template management for workspace and company-level customization of
      signing request notifications
  - name: Organization Seals
    description: >-
      Organization seal management: create, update, revoke, and erase seals
      applied to signing requests
  - name: Signer Terms
    description: >-
      Custom signer terms-of-service / consent statements, company-level with
      per-language workspace overrides
paths:
  /signing-requests/{id}:
    patch:
      tags:
        - Signing Requests
      summary: Partially Update Signing Request
      description: >-
        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, except for
        a seal swap (see `seal_participant`). A `seal_participant` that names a
        seal answers 404 `NOT_FOUND` when the seal does not exist or belongs to
        another company, and 400 `SEAL_UNAVAILABLE` when the seal is revoked,
        deleted or not the current version of its lineage, and also when it is
        limited to a workspace other than the signing request's. These answers
        are for adding a seal participant and for changing its seal. A seal swap
        (`swap_to_seal_id`) answers differently for the new seal: 404
        `NOT_FOUND` when it does not exist, belongs to another company or is
        limited to a workspace other than the signing request's; 409
        `SEAL_UNAVAILABLE` when it is revoked, deleted or not the current
        version of its lineage; 400 `SEAL_FIELD_REQUIRED` when the seal
        participant has no stamp field on the signing request. Adding a seal
        participant or changing its seal answers 503 `SEALS_DISABLED` when
        organization seals are not enabled. Adding a seal participant requires
        `order` (see the order contract). A field that belongs to a seal
        participant accepts only `position` and `page_number` changes; every
        other key of `field`, `recipient_id` included, is ignored.
      operationId: patchSigningRequest
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Signing request ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  description: Update signing request properties only
                  properties:
                    name:
                      type: string
                      maxLength: 255
                      description: New name for signing request
                    description:
                      type: string
                      description: New description
                    document:
                      type: string
                      format: byte
                      description: >-
                        Replace document with new base64-encoded PDF. Page count
                        will be auto-extracted.
                    expiration_hours:
                      type: integer
                      minimum: 1
                      description: New expiration hours
                    settings:
                      $ref: '#/components/schemas/SigningRequestSettings'
                      description: Update settings
                    language:
                      type: string
                      nullable: true
                      enum:
                        - en
                        - es
                        - it
                        - pt
                        - fr
                        - de
                        - el
                        - ru
                        - pl
                        - cs
                        - sv
                        - nl
                        - ro
                        - nb
                        - ca
                      description: >-
                        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:
                      type: string
                      nullable: true
                      description: >-
                        Heading shown on the completion page after signing. Null
                        or an empty string clears the override; omitted leaves
                        it unchanged.
                      maxLength: 200
                    completion_message:
                      type: string
                      nullable: true
                      description: >-
                        Body text shown on the completion page after signing.
                        Null or an empty string clears the override; omitted
                        leaves it unchanged.
                      maxLength: 1000
                    completion_redirect_url:
                      type: string
                      format: uri
                      nullable: true
                      description: >-
                        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.
                      maxLength: 2000
                    completion_redirect_delay:
                      type: integer
                      nullable: true
                      description: >-
                        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.
                      minimum: 0
                      maximum: 30
                - type: object
                  required:
                    - recipient
                  description: Create or update a single recipient
                  properties:
                    recipient:
                      $ref: '#/components/schemas/Recipient'
                      description: >-
                        Recipient to create (omit id) or update (include id).
                        When updating first_name or last_name, the name field is
                        automatically reconstructed using existing values from
                        database for any field not provided. Result: 'First
                        Last' if both exist, 'First' if only first_name.
                - type: object
                  required:
                    - field
                  description: Create or update a single field
                  properties:
                    field:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Include to update existing field, omit to create new
                        type:
                          type: string
                          enum:
                            - text
                            - signature
                            - date
                            - checkbox
                            - initial
                            - initials
                            - dropdown
                            - radio_buttons
                            - textarea
                            - text_area
                            - url
                            - file
                            - stamp
                            - approval_signature
                            - approval_checkmark
                            - approval_date
                          description: >-
                            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:
                          type: object
                          properties:
                            x:
                              type: number
                              description: X position on document
                            'y':
                              type: number
                              description: Y position on document
                            width:
                              type: number
                              description: Field width
                            height:
                              type: number
                              description: Field height
                          description: >-
                            Position object. All properties required for new
                            fields.
                        page_number:
                          type: integer
                          minimum: 1
                          description: Page number (1-indexed). Required for new fields.
                        required:
                          type: boolean
                          description: Whether field is required
                        recipient_id:
                          type: string
                          format: uuid
                          nullable: true
                          description: >-
                            Recipient ID to assign the field to; `null` removes
                            the field's recipient and leaves the field
                            unassigned.
                        variable_name:
                          type: string
                          description: Variable name for prefilled data mapping
                        variable_defined_name:
                          type: string
                          maxLength: 100
                          nullable: true
                          description: >-
                            Human-readable custom field definition name. Can be
                            used as an alternative to variable_name for
                            targeting fields in template-based creation.
                        dropdown_options:
                          description: Options for dropdown fields
                          oneOf:
                            - type: array
                              items:
                                type: string
                            - type: object
                        format_rules:
                          type: object
                          description: >-
                            Format rules (e.g., date format, urlDisplayText for
                            url fields, acceptedFileTypes for file fields)
                        validation_rules:
                          type: object
                          description: Validation rules for the field
                        multi_group_id:
                          type: string
                          format: uuid
                          description: Group ID for radio button groups
                        date_default:
                          type: string
                          description: Default date value
                        date_signing_default:
                          type: boolean
                          description: For date fields, use signing date as default
                        read_only:
                          type: boolean
                          description: >-
                            Whether field is read-only (automatically true for
                            url fields)
                        read_only_value:
                          type: string
                          description: >-
                            Static value for read-only fields. For url fields,
                            this is the URL to link to.
                        final_value:
                          type: string
                          description: >-
                            Final value of the field (for pre-filled read-only
                            fields)
                    documents_layout_version:
                      type: integer
                      minimum: 0
                      description: >-
                        The `documents_layout_version` of your last read
                        (multi-document). Required for a field write on a
                        signing request with more than one document or a layout
                        version above 1 (`409
                        DOCUMENTS_LAYOUT_VERSION_REQUIRED`); a stale value
                        answers `409 DOCUMENT_SET_VERSION_CONFLICT`; a value
                        that is not a non-negative integer answers `400
                        VALIDATION_ERROR` with key `documents_layout_version`.
                - type: object
                  required:
                    - seal_participant
                  description: >-
                    Add, update or swap one seal participant of the signing
                    request. Send only the `seal_participant` key.
                  properties:
                    seal_participant:
                      type: object
                      description: >-
                        One of three uses, chosen by the keys sent; each answers
                        `{ "seal_participant": ... }`. Add: send `seal_id` and
                        `order` without `id`; answers 201. Update: send `id`
                        with `order` to move the participant (a `seal_id` sent
                        together with `order` is ignored), or `id` with
                        `seal_id` alone to change its seal; answers 200. Add and
                        update are possible only before the request is sent (409
                        `ALREADY_SENT` afterwards). Swap: send `id` with
                        `swap_to_seal_id` to replace the seal of a paused seal
                        participant; answers 200. A swap is possible only on a
                        request that was sent and is not finished or cancelled
                        (409 `SEAL_MUTATION_NOT_ALLOWED` on a request that was
                        not sent, and when the participant is not paused), and
                        only with an API key of the protected workspace (403
                        `PROTECTED_KEY_REQUIRED` otherwise). When
                        `swap_to_seal_id` is sent, `seal_id` and `order` are
                        ignored.
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: >-
                            ID of the seal participant to update or swap. Omit
                            it to add a seal participant.
                        seal_id:
                          type: string
                          format: uuid
                          description: >-
                            ID of the organization seal. Required to add a seal
                            participant; on an update without `order` it becomes
                            the seal of the participant. The seal must belong to
                            the company, be the current version of its lineage,
                            be neither revoked nor deleted, and not be limited
                            to another workspace.
                        order:
                          type: integer
                          minimum: 1
                          description: >-
                            Position in the signing order, shared with the
                            recipients' order space. Required to add a seal
                            participant; on an update it moves the participant.
                        swap_to_seal_id:
                          type: string
                          format: uuid
                          description: >-
                            ID of the organization seal that replaces the seal
                            of a paused seal participant on a sent request.
            examples:
              update-properties:
                summary: Update properties
                value:
                  name: Updated Contract Name
                  expiration_hours: 72
              update-recipient:
                summary: Update single recipient
                value:
                  recipient:
                    id: rec123-e89b-12d3-a456-426614174000
                    first_name: John
                    last_name: Smith
                    email: john.smith@example.com
                    designation: Signer
                    order: 1
              add-recipient:
                summary: Add new recipient
                value:
                  recipient:
                    first_name: Jane
                    last_name: Doe
                    email: jane@example.com
                    designation: Signer
                    order: 2
              create-url-field:
                summary: Create URL field
                value:
                  field:
                    type: url
                    position:
                      x: 100
                      'y': 200
                      width: 150
                      height: 30
                    page_number: 1
                    read_only_value: https://example.com/terms
                    format_rules:
                      urlDisplayText: View Terms & Conditions
              create-file-field:
                summary: Create file upload field
                value:
                  field:
                    type: file
                    position:
                      x: 100
                      'y': 300
                      width: 200
                      height: 40
                    page_number: 1
                    required: true
                    format_rules:
                      acceptedFileTypes: image_and_pdf
              update-field:
                summary: Update existing field position
                value:
                  field:
                    id: field123-e89b-12d3-a456-426614174000
                    position:
                      x: 120
                      'y': 220
      responses:
        '200':
          description: >-
            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; a seal participant update or swap returns `{
            "seal_participant": <SealParticipantApi> }`. Response may include a
            'warning' field for email format validation warnings (non-blocking).
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Rate limit: 120 requests per minute'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    description: Response when updating properties
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      template_description:
                        type: string
                        nullable: true
                      document_url:
                        type: string
                        format: uri
                      expiration_hours:
                        type: integer
                  - type: object
                    description: Response when updating/creating a recipient
                  - type: object
                    description: Response when updating/creating a field
                  - type: object
                    description: >-
                      Response when updating a seal participant or swapping its
                      seal
                    required:
                      - seal_participant
                    properties:
                      seal_participant:
                        $ref: '#/components/schemas/SealParticipantApi'
        '201':
          description: >-
            A recipient, a field or a seal participant was created. The body is
            the created recipient or field object; for a seal participant it is
            `{ "seal_participant": <SealParticipantApi> }`. Updating a seal
            participant answers 200 with the same `{ "seal_participant": ... }`
            body.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Rate limit: 120 requests per minute'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    description: The created recipient
                  - type: object
                    description: The created field
                  - type: object
                    description: The created seal participant
                    required:
                      - seal_participant
                    properties:
                      seal_participant:
                        $ref: '#/components/schemas/SealParticipantApi'
        '400':
          description: >-
            Bad Request - Cannot update both properties and recipient in same
            request. Multi-document: `PAGE_COUNT_MISMATCH`,
            `DIMENSION_MISMATCH`, `ANCHOR_MISMATCH` (inline document
            replacement; `ANCHOR_MISMATCH`: the anchors of the replacement do
            not resolve as stored). Multi-document field writes:
            `VALIDATION_ERROR` with key `page` (a page beyond the document's
            page count) or `documents_layout_version`. Organization seals:
            `SEAL_FIELD_REQUIRED` when a seal swap is sent for a seal
            participant that has no stamp field on the signing request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                mixed-update:
                  value:
                    error: Invalid request
                    message: >-
                      Cannot update both properties and recipient in the same
                      request
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: >-
            A seal swap (`swap_to_seal_id`) was sent with an API key that is not
            of the protected workspace (`PROTECTED_KEY_REQUIRED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Signing request or seal participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    error: Signing request not found
                    code: NOT_FOUND
                seal_not_found:
                  value:
                    error: Seal not found
                    code: NOT_FOUND
        '409':
          description: >-
            Conflict: `MULTI_DOCUMENT_READ_ONLY`, `ALREADY_SENT`,
            `ALREADY_FINISHED`, `ALREADY_CANCELLED`, `SEND_IN_PROGRESS`,
            `DOCUMENTS_LAYOUT_VERSION_REQUIRED`,
            `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_BUSY`,
            `DOCUMENT_SET_DISPATCH_STALE`, `DOCUMENT_CANDIDATE_EXPIRED`,
            `DOCUMENT_SET_INCONSISTENT`, `SIGNED_DATA_IMMUTABLE`,
            `MULTI_DOCUMENT_REPLACE_UNSUPPORTED`, `SEAL_MUTATION_NOT_ALLOWED`,
            `SEAL_UNAVAILABLE`. `MULTI_DOCUMENT_REPLACE_UNSUPPORTED`: an inline
            `document` on a request with more than one document (use the
            /documents routes). `SEAL_MUTATION_NOT_ALLOWED`: a seal swap on a
            request that was not sent, or of a seal participant that is not
            paused. `SEAL_UNAVAILABLE`: the new seal of a seal swap is revoked,
            deleted or not the current version of its lineage.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/MultiDocumentError'
                  - allOf:
                      - $ref: '#/components/schemas/Error'
                      - type: object
                        required:
                          - error
                          - code
                        properties:
                          code:
                            type: string
                            enum:
                              - SEAL_UNAVAILABLE
        '429':
          $ref: '#/components/responses/RateLimitError'
        '503':
          description: >-
            Organization seals are not enabled and a seal participant is added
            or its seal is changed (`SEALS_DISABLED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: TypeScript
          label: '@firma-dev/sdk'
          source: |-
            import { FirmaClient } from "@firma-dev/sdk";

            const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

            const response = await firma.signingRequests.patchSigningRequest({
                id: "id",
                body: {
                    name: "Updated Contract Name",
                    expiration_hours: 72
                }
            });
            console.log(response);
components:
  schemas:
    SigningRequestSettings:
      type: object
      description: >-
        Settings returned by the signing request list and detail endpoints.
        Templates use the TemplateSettings schema (no identity fields).
      properties:
        allow_download:
          type: boolean
          description: Whether recipients can download the document
          default: true
        attach_pdf_on_finish:
          type: boolean
          description: Whether to attach PDF when signing is complete
          default: true
        allow_editing_before_sending:
          type: boolean
          description: Whether the signing request can be edited before sending
          default: false
        use_signing_order:
          type: boolean
          description: >-
            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.
          default: true
        hand_drawn_only:
          type: boolean
          description: >-
            When enabled, signers can only hand-draw their signatures and cannot
            use typed/font-based signatures
          default: false
        send_signing_email:
          type: boolean
          description: Whether to send signing request notification emails to signers
          default: true
        send_finish_email:
          type: boolean
          description: Whether to send completion email when all signers finish
          default: true
        send_expiration_email:
          type: boolean
          description: Whether to send expiration notification email when request expires
          default: true
        send_cancellation_email:
          type: boolean
          description: >-
            Whether to send cancellation notification email when request is
            cancelled
          default: true
        require_otp_verification:
          type: boolean
          nullable: true
          description: >-
            Whether signers must verify their email with a one-time code before
            accessing the document; `null` inherits the workspace or company
            setting.
          default: null
        disable_guided_navigation:
          type: boolean
          nullable: true
          description: >-
            Disable automatic scrolling to the next required field during
            signing. Inherits from workspace or company if not set.
        allow_presigning_download:
          type: boolean
          nullable: true
          description: >-
            Allow signers to download the original document before signing;
            `null` inherits the workspace or company setting.
        show_qr_code:
          type: boolean
          nullable: true
          description: >-
            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:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Identity fields signers may edit before signing, for example
            `["name", "company"]`; `null` disables the editing. When set, a
            confirmation dialog lets signers edit the specified fields.
        notify_identity_change_email:
          type: boolean
          default: false
          description: Send an email notification when a signer changes their identity.
    Recipient:
      type: object
      required:
        - first_name
        - email
        - designation
      description: >-
        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. A recipient with
        designation CC is never matched to a template user; it is added as a CC
        recipient, and the template's CC recipients are copied to the signing
        request, skipping any whose email (case-insensitive) is already on a CC
        recipient of the request. **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. An
        existing recipient cannot be changed between CC and Signer/Approver
        (400); delete it and create it again.
      properties:
        id:
          type: string
          description: >-
            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:
          type: string
          description: >-
            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:
          type: string
          format: uuid
          description: >-
            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. Not used for CC recipients, which are never matched to a
            template user.
        first_name:
          type: string
          maxLength: 100
          description: Recipient's first name
        last_name:
          type: string
          maxLength: 100
          description: >-
            Recipient's last name (optional, but required if using full_name or
            last_name prefilled variables)
        email:
          type: string
          format: email
          maxLength: 255
          description: Recipient's email address
        designation:
          type: string
          enum:
            - Signer
            - Approver
            - CC
          description: >-
            Role of the recipient. Signer signs the document, Approver approves
            with approval fields, CC receives a copy when complete.
        order:
          type: integer
          minimum: 1
          description: >-
            Signing sequence number. Recipients must sign in order, with lower
            numbers signing first. This field is required for all recipients.
        phone_number:
          type: string
          maxLength: 50
          nullable: true
          description: Recipient's phone number
        street_address:
          type: string
          maxLength: 255
          nullable: true
          description: Street address
        city:
          type: string
          maxLength: 100
          nullable: true
          description: City
        state_province:
          type: string
          maxLength: 100
          nullable: true
          description: State or province
        postal_code:
          type: string
          maxLength: 20
          nullable: true
          description: Postal/ZIP code
        country:
          type: string
          maxLength: 100
          nullable: true
          description: Country
        title:
          type: string
          maxLength: 100
          nullable: true
          description: Job title
        company:
          type: string
          maxLength: 255
          nullable: true
          description: Company name
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom key-value pairs for additional recipient data
    SealParticipantApi:
      type: object
      description: >-
        Seal participant as the API answers it on a signing request or a
        template. Every key is always present; nullable keys are null when
        unset.
      required:
        - id
        - order
        - seal
        - status
        - applied_at
        - paused_at
        - pause_reason
        - swapped_from_seal_id
        - triggered_by_recipient_id
        - sender_kind
        - seal_out_of_scope
      properties:
        id:
          type: string
          format: uuid
        order:
          type: integer
          minimum: 1
          description: >-
            Position in the signing order, shared with the recipients' order
            space.
        seal:
          type: object
          description: The organization seal this participant applies.
          required:
            - id
            - lineage_id
            - name
            - version
            - display_name
          properties:
            id:
              type: string
              format: uuid
            lineage_id:
              type: string
              format: uuid
              description: Shared across versions of the same seal
            name:
              type: string
            version:
              type: integer
            display_name:
              type: string
        status:
          type: string
          enum:
            - pending
            - paused
            - applied
          description: >-
            applied when applied_at is set, else paused when paused_at is set,
            else pending.
        applied_at:
          type: string
          format: date-time
          nullable: true
        paused_at:
          type: string
          format: date-time
          nullable: true
        pause_reason:
          type: string
          nullable: true
          enum:
            - seal_revoked_stop_pending
            - seal_integrity_mismatch
            - null
        swapped_from_seal_id:
          type: string
          format: uuid
          nullable: true
        triggered_by_recipient_id:
          type: string
          format: uuid
          nullable: true
          description: The recipient whose action applied the seal.
        sender_kind:
          type: string
          nullable: true
          enum:
            - dashboard
            - api_key
            - embedded
            - null
        seal_out_of_scope:
          type: boolean
          description: >-
            True when the seal belongs to a workspace other than the signing
            request's or the template's.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: >-
            Machine-readable error code Seal-related codes: SEALS_DISABLED,
            SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE,
            SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID,
            SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_NO_IMAGE_FIELD,
            SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN,
            SEAL_UNAVAILABLE Multi-document codes: see MultiDocumentErrorCode
            (41 codes).
        errors:
          type: array
          description: >-
            All validation errors when multiple failures are reported together.
            The top-level error repeats the first item for backward
            compatibility.
          items:
            type: object
            required:
              - message
            properties:
              message:
                type: string
        message:
          type: string
          description: Detailed error description
        details:
          type: object
          description: Additional error details
          additionalProperties: true
      required:
        - error
      description: >-


        Organization Seal error codes: SEALS_DISABLED, SEAL_ALREADY_REVOKED,
        SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE,
        SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND,
        SEAL_NO_IMAGE_FIELD, SEAL_ORDER_COLLISION, SEAL_PAUSED,
        SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE
    MultiDocumentError:
      description: An error answered by a multi-document route.
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          required:
            - error
            - code
          properties:
            code:
              $ref: '#/components/schemas/MultiDocumentErrorCode'
    MultiDocumentErrorCode:
      type: string
      enum:
        - ALREADY_CANCELLED
        - ALREADY_FINISHED
        - ALREADY_SENT
        - ANCHOR_DOCUMENT_REQUIRED
        - ANCHOR_MISMATCH
        - CONFLICTING_DOCUMENT_SOURCE
        - DIMENSION_MISMATCH
        - DOCUMENTS_LAYOUT_VERSION_REQUIRED
        - DOCUMENT_CANDIDATE_EXPIRED
        - DOCUMENT_NOT_FOUND
        - DOCUMENT_ORIGINAL_NOT_AVAILABLE
        - DOCUMENT_SET_BUSY
        - DOCUMENT_SET_DISPATCH_STALE
        - DOCUMENT_SET_INCONSISTENT
        - DOCUMENT_SET_LOCKED
        - DOCUMENT_SET_TOO_LARGE
        - DOCUMENT_SET_VERSION_CONFLICT
        - DOCUMENT_SIGNED_NOT_AVAILABLE
        - DOCUMENT_UPLOAD_NOT_FOUND
        - DUPLICATE_DOCUMENT_ID
        - FENCE_COLUMN_PROTECTED
        - INSUFFICIENT_CREDITS
        - INTERNAL
        - INTERNAL_ERROR
        - INVALID_DOCUMENT_ORDER
        - INVALID_SIGNING_ORDER
        - MAX_DOCUMENTS_EXCEEDED
        - MIN_DOCUMENTS_REQUIRED
        - MULTI_DOCUMENT_READ_ONLY
        - MULTI_DOCUMENT_REPLACE_UNSUPPORTED
        - NOT_FOUND
        - PAGE_COUNT_MISMATCH
        - PARTICIPANTS_CHANGED
        - RATE_LIMIT_EXCEEDED
        - SEAL_MUTATION_NOT_ALLOWED
        - SEND_EFFECTS_EXIST
        - SEND_IN_PROGRESS
        - SIGNED_DATA_IMMUTABLE
        - SIGNING_ORDER_LOCKED_APPLIED
        - SIGNING_ORDER_LOCKED_SENDING
        - SIGNING_ORDER_LOCKED_SENT
        - VALIDATION_ERROR
      description: >-
        Error codes of the multi-document contract and of the routes it changes
        (generated from the error matrix's API-surfaced rows). A genuine server
        fault answers 500 with INTERNAL_ERROR on the legacy routes and INTERNAL
        on the shared HttpError paths (multi-document dispatch, the RPC status
        map, document-set routes); neither carries detail.
  responses:
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    RateLimitError:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp of reset
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Use your API key directly without any prefix
        (e.g., 'your-api-key'). Bearer prefix is optional but not required.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.