> ## 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.

# Create and Send Signing Request (Atomic)

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



## OpenAPI

````yaml api-reference/v01.39.01/openapi-v01.39.01.json post /signing-requests/create-and-send
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/create-and-send:
    post:
      tags:
        - Signing Requests
      summary: Create and Send Signing Request (Atomic)
      description: >-
        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)
      operationId: createAndSendSigningRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Signing request name
                  example: Employment Contract - John Doe
                description:
                  type: string
                  description: Signing request description
                  example: Full-time employment contract for Software Engineer position
                document:
                  type: string
                  format: byte
                  description: >-
                    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.
                  example: >-
                    JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...
                template_id:
                  type: string
                  format: uuid
                  description: >-
                    Template ID to use (mutually exclusive with document and
                    document_id).


                    **Seals.** If the template has seal participants and
                    `seal_participants` is absent or `null`, the request
                    inherits them and the template fields that belong to them.
                    An array, including `[]`, replaces them: the template's seal
                    participants and their fields are not copied. Any other type
                    answers 400 `VALIDATION_ERROR`. A kept seal and the
                    recipients are renumbered together into one contiguous order
                    sequence that keeps the template's relative order. When the
                    template has no recipients of its own, inherited seals are
                    placed after the request's recipients. A template seal
                    follows the current version of its lineage: the request
                    attaches the current version, not the version the template
                    points at. If that current version is revoked or deleted, or
                    the lineage has no current version, the call answers 409
                    `SEAL_UNAVAILABLE` and creates nothing. A template seal that
                    the API key's company cannot see, or whose current version
                    is limited to a workspace other than the API key's
                    workspace, is not copied and neither are its fields; the
                    request is still created and `seal_participants` lists the
                    seal as a dropped entry (`dropped: true`). If a seal would
                    be kept while organization seals are not enabled, the call
                    answers 503 `SEALS_DISABLED`.
                  example: 123e4567-e89b-12d3-a456-426614174000
                expiration_hours:
                  type: integer
                  minimum: 1
                  default: 168
                  description: 'Hours until signing request expires (default: 168 = 7 days)'
                  example: 168
                recipients:
                  type: array
                  description: >-
                    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.
                    Recipients with designation CC are never matched to template
                    users; they are added as CC recipients. 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.
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/Recipient'
                fields:
                  type: array
                  description: Array of fields to be filled (document-based only)
                  items:
                    type: object
                    required:
                      - type
                      - page
                      - x
                      - 'y'
                    properties:
                      recipient_id:
                        type: string
                        description: >-
                          Temporary ID or UUID of recipient assigned to this
                          field
                        example: temp_signer_1
                      type:
                        type: string
                        enum:
                          - signature
                          - initial
                          - text
                          - date
                          - checkbox
                          - dropdown
                          - radio_buttons
                          - text_area
                          - url
                          - file
                          - stamp
                          - approval_signature
                          - approval_checkmark
                          - approval_date
                        description: >-
                          Field type. Accepts aliases: "initials" (normalized to
                          "initial"), "textarea" (normalized to "text_area"),
                          "radio" (normalized to "radio_buttons").
                        example: signature
                      page:
                        type: integer
                        minimum: 1
                        description: PDF page number (1-indexed)
                        example: 1
                      x:
                        type: number
                        description: X coordinate on page
                        example: 100
                      'y':
                        type: number
                        description: Y coordinate on page
                        example: 200
                      width:
                        type: number
                        default: 200
                        example: 200
                      height:
                        type: number
                        default: 50
                        example: 50
                      variable_name:
                        type: string
                        description: >-
                          Variable name for prefilled data (e.g.,
                          'phone_number', 'company'). If set, the corresponding
                          recipient field must be populated.
                        enum:
                          - first_name
                          - last_name
                          - full_name
                          - email
                          - phone_number
                          - street_address
                          - city
                          - state_province
                          - postal_code
                          - country
                          - title
                          - company
                        example: phone_number
                      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.
                      required:
                        type: boolean
                        default: false
                        description: Whether field is required
                      read_only:
                        type: boolean
                        default: false
                        description: Whether field is read-only (pre-filled)
                      final_value:
                        type: string
                        description: >-
                          Pre-filled value for read-only fields (required if
                          read_only=true and required=true)
                        example: Software Engineer
                      background_color:
                        type: string
                        nullable: true
                        pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
                        description: Background color as hex (e.g., '#FFFDE7')
                        example: '#FFFDE7'
                      dropdown_options:
                        description: >-
                          Options for dropdown fields. Required when type is
                          "dropdown".
                        example:
                          - Option A
                          - Option B
                          - Option C
                        oneOf:
                          - type: array
                            items:
                              type: string
                          - type: object
                      seal_participant_temp_id:
                        type: string
                        description: >-
                          Temporary ID of the seal participant this field is
                          assigned to (matches temp_id in seal_participants
                          array)
                      seal_attribute:
                        type: string
                        enum:
                          - display_name
                          - signatory_title
                          - null
                        nullable: true
                        description: >-
                          Which text a seal-owned text field shows: the seal's
                          display name (`display_name`) or the signatory title
                          (`signatory_title`). It applies to a field that a seal
                          participant owns (a field with
                          `seal_participant_temp_id`, or a template field that
                          belongs to a seal participant) and is ignored on any
                          other field. It is stored on the field as
                          `format_rules.sealAttribute`; on a template-based
                          request it replaces the `sealAttribute` that the
                          template field carries and leaves the rest of the
                          template field's `format_rules` unchanged. Any other
                          value answers 400 `VALIDATION_ERROR`; this check
                          applies to every field in the body, whether or not a
                          seal owns it.
                anchor_tags:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/AnchorTag'
                  description: >-
                    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).
                reminders:
                  type: array
                  description: Array of reminder configurations
                  items:
                    type: object
                    required:
                      - hours_before_expiration
                    properties:
                      hours_before_expiration:
                        type: integer
                        minimum: 1
                        description: Hours before expiration to send reminder
                        example: 24
                settings:
                  type: object
                  description: Signing request settings
                  properties:
                    use_signing_order:
                      type: boolean
                      default: true
                      description: >-
                        Enforce signing order based on recipient.order. When
                        false, all signers receive the document simultaneously.
                    allow_download:
                      type: boolean
                      default: true
                      description: Allow recipients to download document
                    attach_pdf_on_finish:
                      type: boolean
                      default: true
                      description: Attach completed PDF to completion email
                    send_signing_email:
                      type: boolean
                      default: true
                      description: Send email notification to signers
                    send_finish_email:
                      type: boolean
                      default: true
                      description: Send email when all signatures complete
                    send_expiration_email:
                      type: boolean
                      default: true
                      description: Send email when request expires
                    send_cancellation_email:
                      type: boolean
                      default: true
                      description: Send email when request is cancelled
                    hand_drawn_only:
                      type: boolean
                      default: false
                      description: >-
                        Require signers to hand-draw their signatures instead of
                        using typed signatures
                    identity_editable_fields:
                      type: array
                      nullable: true
                      items:
                        type: string
                        enum:
                          - name
                          - company
                          - title
                          - phone
                          - address
                      description: >-
                        Identity fields signers can edit before signing; `null`
                        disables the editing. When set, a confirmation dialog
                        appears allowing signers to edit the specified fields.
                      example:
                        - name
                        - company
                    notify_identity_change_webhook:
                      type: boolean
                      default: false
                      description: Send webhook event when a signer changes their identity
                    notify_identity_change_email:
                      type: boolean
                      default: false
                      description: >-
                        Send email notification when a signer changes their
                        identity
                document_id:
                  type: string
                  format: uuid
                  description: >-
                    ID of a previously uploaded document (mutually exclusive
                    with document and template_id). Obtain by calling POST
                    /documents first.
                  example: 123e4567-e89b-12d3-a456-426614174000
                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. Falls
                    back to the template value (when template_id is used), then
                    the workspace and company defaults.
                  example: Thank you for signing
                  maxLength: 200
                completion_message:
                  type: string
                  nullable: true
                  description: >-
                    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.
                  example: Your signed copy is on its way to your inbox.
                  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). Falls back to
                    the template value (when template_id is used), then the
                    workspace and company defaults.
                  example: https://example.com/thank-you
                  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. Falls back to the template value (when
                    template_id is used), then the workspace and company
                    defaults.
                  example: 5
                  minimum: 0
                  maximum: 30
                seal_participants:
                  type: array
                  items:
                    $ref: '#/components/schemas/SealParticipantInput'
                  description: >-
                    Organization seal participants for the new signing request:
                    with `template_id`, omit the key or send `null` to inherit
                    the template's seals, send `[]` for no seals, or send an
                    array to replace them. A replaced template seal and its
                    fields are not copied. Any other type answers 400
                    `VALIDATION_ERROR`. On a template-based request the seal
                    orders and the recipients' orders are renumbered together
                    into one contiguous sequence, whether the seals are
                    inherited or sent in the array. A non-empty array, or an
                    inherited seal that would be kept, requires organization
                    seals to be enabled; otherwise the call answers 503
                    `SEALS_DISABLED`.
                  nullable: true
                document_ids:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: string
                    format: uuid
                  description: >-
                    Temporary upload ids from POST /documents, in document
                    order, to create a multi-document signing request
                    (enablement required). Exactly one of document, document_id
                    or document_ids or template_id (`400
                    CONFLICTING_DOCUMENT_SOURCE`); a repeated id answers `400
                    DUPLICATE_DOCUMENT_ID`, more than 20 `400
                    MAX_DOCUMENTS_EXCEEDED`, an unknown or expired upload `400
                    DOCUMENT_UPLOAD_NOT_FOUND`, a set above 100 MB `413
                    DOCUMENT_SET_TOO_LARGE`; more than one id for a company not
                    enabled answers `409 MULTI_DOCUMENT_READ_ONLY`.
              oneOf:
                - required:
                    - document
                - required:
                    - template_id
                - required:
                    - document_ids
            examples:
              document-based:
                summary: Create and send with document
                value:
                  name: Employment Contract - John Doe
                  description: Full-time employment contract
                  document: JVBERi0xLjQKJeLjz9MK...
                  expiration_hours: 168
                  recipients:
                    - id: temp_signer_1
                      first_name: John
                      last_name: Doe
                      email: john.doe@example.com
                      designation: Signer
                      order: 1
                      phone_number: +1-555-0123
                      company: Acme Corp
                      title: Software Engineer
                  fields:
                    - recipient_id: temp_signer_1
                      type: signature
                      page: 1
                      x: 100
                      'y': 500
                      width: 200
                      height: 50
                    - recipient_id: temp_signer_1
                      type: text
                      page: 1
                      x: 100
                      'y': 400
                      width: 150
                      height: 30
                      variable_name: phone_number
                      required: true
                      read_only: true
                  settings:
                    use_signing_order: true
                    send_signing_email: true
              template-based:
                summary: Create and send from template
                value:
                  name: NDA - Jane Smith
                  template_id: 123e4567-e89b-12d3-a456-426614174000
                  recipients:
                    - first_name: Jane
                      last_name: Smith
                      email: jane.smith@example.com
                      designation: Signer
                      order: 1
                      company: Tech Startup Inc
                  expiration_hours: 72
      responses:
        '201':
          description: >-
            Signing request created and sent successfully. The response may
            include non-blocking anchor-tag warnings.
          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:
                $ref: '#/components/schemas/CreateAndSendResponse'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: Employment Contract - John Doe
                description: Full-time employment contract
                status: sent
                document_url: https://storage.supabase.co/...
                page_count: 3
                expiration_hours: 168
                settings:
                  use_signing_order: true
                  allow_download: true
                  attach_pdf_on_finish: true
                  send_signing_email: true
                  send_finish_email: true
                  send_expiration_email: true
                  send_cancellation_email: true
                  hand_drawn_only: false
                created_date: '2026-01-12T10:30:00Z'
                sent_date: '2026-01-12T10:30:00Z'
                template_id: null
                first_signer:
                  id: rec456-e89b-12d3-a456-426614174000
                  name: John Doe
                  email: john.doe@example.com
                  signing_link: >-
                    https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000
                recipients:
                  - id: rec456-e89b-12d3-a456-426614174000
                    first_name: John
                    last_name: Doe
                    name: John Doe
                    email: john.doe@example.com
                    designation: Signer
                    order: 1
                fields:
                  - id: field123-e89b-12d3-a456-426614174000
                    field_type: signature
                    seal_participant_id: null
                credits_remaining: 99
        '400':
          description: >-
            Validation error - invalid input or missing required signer data.
            Multi-document: `CONFLICTING_DOCUMENT_SOURCE`,
            `DUPLICATE_DOCUMENT_ID`, `MAX_DOCUMENTS_EXCEEDED`,
            `DOCUMENT_UPLOAD_NOT_FOUND`, `ANCHOR_DOCUMENT_REQUIRED`.
            Organization seals: `VALIDATION_ERROR` when `seal_participants` is
            neither an array nor `null`, when one of its entries has no
            `temp_id`, repeats a `temp_id` or has an `order` that is not a
            positive integer, or when the `seal_attribute` of a field is not
            `display_name`, `signatory_title` or `null`; `SEAL_UNAVAILABLE` when
            an entry omits `seal_id` and neither the workspace nor the company
            has an active default seal; on a document-based request with seal
            participants, `INVALID_SIGNING_ORDER` when a recipient has no
            `order` or the recipients and the seals do not form one sequence
            starting at 1, and `SEAL_ORDER_COLLISION` when two of them
            (recipients or seals) share an `order`. At the send step,
            `SEAL_NO_IMAGE_FIELD` when a seal participant of the request owns no
            field of type `stamp` (its seal image field): the request is not
            sent and no signing request is kept.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndSendValidationError'
              examples:
                missing-recipient-data:
                  value:
                    error: >-
                      One or more signers are missing required information for
                      sending
                    phase: send_validation
                    validation_errors:
                      - recipient_index: 1
                        recipient_email: john@example.com
                        missing_fields:
                          - phone_number
                          - company
                invalid-document:
                  value:
                    error: Document must be valid base64-encoded PDF
                    phase: create_validation
                seal-no-image-field:
                  summary: A seal participant has no seal image field
                  value:
                    error: >-
                      Each organization seal needs at least one seal image
                      field.
                    code: SEAL_NO_IMAGE_FIELD
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '404':
          description: >-
            The template was not found or is not in the API key's workspace. A
            seal named in `seal_participants` does not exist, belongs to another
            company or is limited to another workspace (`NOT_FOUND`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict: `SEAL_UNAVAILABLE` (a seal named in `seal_participants` is
            revoked or deleted, or is not the current version of its lineage; or
            the current version of an inherited template seal is revoked or
            deleted, or that seal has no current version),
            `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`,
            `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`,
            `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`,
            `DOCUMENT_SET_DISPATCH_STALE`. `SEND_EFFECTS_EXIST` and
            `ALREADY_SENT` may also carry `signing_request_id`: it is present
            when the signing request this call created was kept (its rollback
            was refused), so recover that request instead of retrying, since a
            retry creates a second request; without it, no request was kept.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CreateAndSendConflictError'
                  - allOf:
                      - $ref: '#/components/schemas/Error'
                      - type: object
                        required:
                          - error
                          - code
                        properties:
                          code:
                            type: string
                            enum:
                              - SEAL_UNAVAILABLE
        '413':
          description: DOCUMENT_SET_TOO_LARGE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiDocumentError'
        '422':
          description: >-
            Recipient email address is suppressed (previously bounced or marked
            as spam) and cannot be sent to
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          description: >-
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Anchor-tag processing is disabled on the edge fallback
            (`ANCHOR_DISABLED_EDGE`): retry through the primary API route. Or
            organization seals are not enabled and either `seal_participants` is
            a non-empty array (answered before its entries are checked) or
            template inheritance keeps at least one seal (`SEALS_DISABLED`).
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - ANCHOR_DISABLED_EDGE
                      - SEALS_DISABLED
      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.createAndSendSigningRequest({
                "name": "Employment Contract - John Doe",
                "description": "Full-time employment contract",
                "document": "JVBERi0xLjQKJeLjz9MK...",
                "expiration_hours": 168,
                "recipients": [
                    {
                        "id": "temp_signer_1",
                        "first_name": "John",
                        "last_name": "Doe",
                        "email": "john.doe@example.com",
                        "designation": "Signer",
                        "order": 1,
                        "phone_number": "+1-555-0123",
                        "company": "Acme Corp",
                        "title": "Software Engineer"
                    }
                ],
                "fields": [
                    {
                        "recipient_id": "temp_signer_1",
                        "type": "signature",
                        "page": 1,
                        "x": 100,
                        "y": 500,
                        "width": 200,
                        "height": 50
                    },
                    {
                        "recipient_id": "temp_signer_1",
                        "type": "text",
                        "page": 1,
                        "x": 100,
                        "y": 400,
                        "width": 150,
                        "height": 30,
                        "variable_name": "phone_number",
                        "required": true,
                        "read_only": true
                    }
                ],
                "settings": {
                    "use_signing_order": true,
                    "send_signing_email": true
                }
            });

            console.log(response);
components:
  schemas:
    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
    AnchorTag:
      type: object
      additionalProperties: false
      required:
        - anchor_string
        - type
        - recipient_id
      description: >-
        Anchor tag definition for automatic field placement. Anchor tags are
        text markers embedded in a PDF document (e.g., '{{SIGN_HERE}}') that are
        automatically located and converted into positioned fields. The anchor
        text is removed from the PDF after processing by default.
      properties:
        anchor_string:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Text string to search for in the PDF document. Common patterns
            include '{{SIGN_HERE}}', '{{DATE}}', etc.
          example: '{{SIGN_HERE}}'
        type:
          type: string
          enum:
            - signature
            - initial
            - initials
            - text
            - date
            - checkbox
            - radio_buttons
            - radio
            - dropdown
            - textarea
            - text_area
            - url
            - approval_signature
            - approval_checkmark
            - approval_date
          description: Type of field to place at the anchor location
        recipient_id:
          oneOf:
            - type: integer
            - type: string
          description: >-
            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.
          example: temp_1
        x_offset:
          type: number
          description: >-
            Horizontal offset from anchor position. Units determined by
            offset_units (default: percent of page width).
          default: 0
        y_offset:
          type: number
          description: >-
            Vertical offset from anchor position. Units determined by
            offset_units (default: percent of page height).
          default: 0
        offset_units:
          type: string
          enum:
            - percent
            - pixels
          default: percent
          description: >-
            Unit type for x_offset and y_offset. 'percent' = percentage of page
            dimensions, 'pixels' = PDF points (72 DPI).
        width:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: >-
            Field width as percentage of page width. Defaults vary by field type
            (e.g., signature=25, text=20, checkbox=3).
        height:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: >-
            Field height as percentage of page height. Defaults vary by field
            type (e.g., signature=5, text=3, checkbox=3).
        case_sensitive:
          type: boolean
          default: false
          description: Whether anchor string matching is case-sensitive
        match_whole_word:
          type: boolean
          default: true
          description: Whether to match whole words only (bounded by non-word characters)
        ignore_if_not_present:
          type: boolean
          default: false
          description: >-
            If true, skip this anchor without error when not found in the
            document. If false (default), a missing anchor causes a validation
            error.
        occurrence:
          type: integer
          minimum: 0
          maximum: 1000
          default: 0
          description: >-
            Which occurrence to place a field on. 0 = all occurrences (default),
            1 = first only, 2 = second only, etc.
        remove_anchor_text:
          type: boolean
          default: true
          description: >-
            Whether to remove the anchor text using corrected glyph geometry and
            sub-pixel text removal. Defaults to true.
        add_white_background:
          type: boolean
          default: false
          description: >-
            Whether to draw a white background across the full resolved field
            rectangle. This is independent of anchor-text removal.
        required:
          type: boolean
          default: true
          description: Whether the field must be completed by the signer
        read_only:
          type: boolean
          default: false
          description: Whether the field is read-only (pre-filled)
        read_only_value:
          type: string
          nullable: true
          maxLength: 10000
          description: Static value for read-only fields
        variable_name:
          type: string
          nullable: true
          maxLength: 255
          description: Variable name for the field
        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.
        background_color:
          type: string
          nullable: true
          pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
          description: Background color as hex (e.g., '#FFFDE7')
          example: '#FFFDE7'
        font_size:
          type: integer
          minimum: 8
          maximum: 48
          description: >-
            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.
          example: 12
        dropdown_options:
          description: Options for dropdown fields
          oneOf:
            - type: array
              items:
                type: string
            - type: object
        date_default:
          type: string
          nullable: true
          maxLength: 50
          description: Default date value
        date_signing_default:
          type: boolean
          default: false
          description: Use signing date as default
        multi_group_id:
          type: string
          nullable: true
          maxLength: 255
          description: Group ID for linking checkbox/radio fields
        document_index:
          type: integer
          minimum: 1
          description: >-
            1-based index into `document_ids` of the document this tag is
            searched in. Optional with one document (defaults to 1); required
            with more than one (`400 ANCHOR_DOCUMENT_REQUIRED`); out of range
            answers `400 VALIDATION_ERROR`.
    SealParticipantInput:
      type: object
      required:
        - temp_id
        - order
      description: >-
        One organization seal participant of a new signing request: an item of
        `seal_participants` on `POST /signing-requests` and `POST
        /signing-requests/create-and-send`.
      properties:
        seal_id:
          type: string
          format: uuid
          description: >-
            ID of the organization seal to apply; omit it to use the default
            seal of the workspace or, when the workspace has none, of the
            company. The call answers 400 `SEAL_UNAVAILABLE` when neither
            exists.
        order:
          type: integer
          minimum: 1
          description: Position in the signing sequence
        temp_id:
          type: string
          description: >-
            Temporary ID of this seal participant, required and unique within
            `seal_participants`; fields of the same request name it in
            `seal_participant_temp_id`.
    CreateAndSendResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Signing request ID
        name:
          type: string
          description: Signing request name
        description:
          type: string
          nullable: true
          description: Signing request description
        status:
          type: string
          enum:
            - sent
          description: Always 'sent' for this endpoint
        document_url:
          type: string
          format: uri
          description: Signed URL to access document
        page_count:
          type: integer
          description: Number of pages in document
        expiration_hours:
          type: integer
          description: Hours until expiration
        settings:
          $ref: '#/components/schemas/SigningRequestSettings'
        created_date:
          type: string
          format: date-time
        sent_date:
          type: string
          format: date-time
          description: When request was sent
        template_id:
          type: string
          format: uuid
          nullable: true
        first_signer:
          type: object
          description: Details of the first signer who received the email
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            email:
              type: string
              format: email
            signing_link:
              type: string
              format: uri
              description: Direct link for signer to access signing view
        recipients:
          type: array
          description: All recipients with real UUIDs
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              first_name:
                type: string
              last_name:
                type: string
                nullable: true
              name:
                type: string
              email:
                type: string
                format: email
              designation:
                type: string
              order:
                type: integer
        fields:
          type: array
          description: >-
            All active fields of the new signing request, including the fields
            owned by seal participants. Each item is the stored field record,
            not the `Field` shape used in requests: for example the field type
            is in `field_type`, and a seal-owned field has no recipient and
            names its seal participant in `seal_participant_id`.
          items:
            type: object
            additionalProperties: true
        seal_participants:
          type: array
          description: >-
            Organization seal participants in the signing order. Empty when the
            request has no seals. Each item is either a persisted seal
            participant (`dropped: false`) or, on a template-based request, an
            entry for a template seal that was not copied because the API key's
            company cannot see the seal or because the seal is limited to
            another workspace (`dropped: true`, `id` and `order` null,
            `seal_out_of_scope: true`). Dropped entries come after the persisted
            ones, in template order. Template seals that an explicit
            `seal_participants` array replaced are not listed.
          items:
            oneOf:
              - $ref: '#/components/schemas/SealParticipantCreated'
              - $ref: '#/components/schemas/SealParticipantDropped'
        credits_remaining:
          type: integer
          description: Company credits remaining after deduction
        warnings:
          type: array
          items:
            type: string
          description: >-
            Optional non-blocking warnings, including unknown anchor-tag
            properties during the compatibility window and anchor-processing
            warnings.
      description: Signing request created and sent
      required:
        - id
        - name
        - status
    CreateAndSendValidationError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: Machine-readable error code
          example: VALIDATION_ERROR
        phase:
          type: string
          enum:
            - create_validation
            - send_validation
          description: Which validation phase failed
        validation_errors:
          type: array
          description: Detailed validation errors for send phase
          items:
            type: object
            properties:
              recipient_index:
                type: integer
                description: 1-based index of recipient
              recipient_email:
                type: string
              missing_fields:
                type: array
                items:
                  type: string
                description: List of missing required fields
        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
      description: Validation error during create-and-send
      required:
        - error
        - code
    InsufficientCreditsError:
      type: object
      properties:
        error:
          type: string
          example: >-
            Insufficient credits. Please purchase more credits to send signing
            requests.
        code:
          type: string
          example: INSUFFICIENT_CREDITS
        current_credits:
          type: integer
          example: 0
      description: Insufficient credits error
      required:
        - error
        - code
        - current_credits
    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
    CreateAndSendConflictError:
      description: >-
        A 409 answered by POST /signing-requests/create-and-send: a
        MultiDocumentError that also names the signing request this call created
        when that request was kept (its rollback was refused with
        `SEND_EFFECTS_EXIST` or `ALREADY_SENT`).
      allOf:
        - $ref: '#/components/schemas/MultiDocumentError'
        - type: object
          properties:
            signing_request_id:
              type: string
              format: uuid
              description: >-
                Present only on SEND_EFFECTS_EXIST and ALREADY_SENT when the
                signing request this call created was kept (its rollback was
                refused): its id, so the caller can recover it instead of
                retrying (a retry creates a second request). Absent when the
                request was rolled back.
    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'
    UnprocessableEntityError:
      type: object
      properties:
        error:
          type: string
          example: A recipient's email address cannot receive messages.
        code:
          type: string
          example: RECIPIENT_EMAIL_SUPPRESSED
      description: Unprocessable entity error
      required:
        - error
        - code
    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.
    SealParticipantCreated:
      description: >-
        A persisted seal participant of the new document: every key of
        SealParticipantApi, plus `dropped: false`.
      allOf:
        - $ref: '#/components/schemas/SealParticipantApi'
        - type: object
          required:
            - dropped
          properties:
            dropped:
              type: boolean
              enum:
                - false
    SealParticipantDropped:
      type: object
      description: >-
        A template seal that was not copied to the new signing request or
        template because it is not available there: the key's company cannot see
        the seal, or the seal is limited to a workspace other than the target
        workspace. The fields that belong to the seal were not copied either.
        `seal` is the summary of the seal's current version, or null when the
        seal is not visible to the key's company.
      required:
        - id
        - order
        - seal
        - seal_out_of_scope
        - dropped
      properties:
        id:
          type: string
          nullable: true
          enum:
            - null
          description: 'Always null: no participant was created.'
        order:
          type: integer
          nullable: true
          enum:
            - null
          description: 'Always null: no participant was created.'
        seal:
          type: object
          nullable: true
          description: >-
            Summary of the seal's current version; null when the API key's
            company cannot see the seal.
          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
        seal_out_of_scope:
          type: boolean
          enum:
            - true
        dropped:
          type: boolean
          enum:
            - true
    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.
    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.
  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.