openapi: 3.0.3
info:
  version: v1
  title: EasyInk API
  description: |-
    The EasyInk Public API allows integration with the e-signature platform
    to manage signing sessions, participants, documents, and complete signing workflows.

    ## Authentication

    All API requests require authentication using JWT Bearer tokens.

    **Including the token in requests:**
    ```
    Authorization: Bearer {your-jwt-token}
    ```

    **How to obtain a token:**

    The API uses the **Authorization Code Flow** (OAuth 2.0) for authentication. This is a three-step process that involves redirecting the user to the Identity Provider and then exchanging an authorization code for an access token.

    1.  **Step 1: Get Client Secret**
    Contact your EasyInk administrator to get the client ID and client secret.

    2.  **Step 2: Get Authorization Code**
        Redirect the user to the authorize endpoint in a browser:
        - Production: `https://identity.easyink.io/connect/authorize`
        - Staging: `https://identity-staging.easyink.io/connect/authorize`

        Callback URL:
        - Production: `https://easyink.io`
        - Staging: `https://staging.easyink.io`

        **Query Parameters:**
        - `response_type`: `code`
        - `client_id`: `{client-id}`
        - `scope`: `openid hermes_api hermes_idp profile`
        - `redirect_uri`: `{prod-or-staging-callback-url}`
        - `code_challenge`: `{random-pkce-challenge}`
        - `code_challenge_method`: `S256`

    3.  **Step 3: Exchange Code for Token**
        After successful login, the user is redirected to your `redirect_uri` with a `code` parameter. Exchange this code for a token:
        - Production: `POST https://identity.easyink.io/connect/token`
        - Staging: `POST https://identity-staging.easyink.io/connect/token`

        **Request Body (URL-encoded):**
        - `grant_type`: `authorization_code`
        - `client_id`: `{client-id}`
        - `client_secret`: `{client-secret}`
        - `code`: `{received-code}`
        - `redirect_uri`: `{prod-or-staging-callback-url}`
        - `code_verifier`: `{pkce-verifier-that-was-used-for-generating-pkce-challenge}`

    **Using Postman:**
    1. In your request, go to the **Authorization** tab.
    2. Select **Type**: `OAuth 2.0`.
    3. In the **Configure New Token** section:
       - **Grant Type**: `Authorization Code (With PKCE)`
       - **Callback URL**: `https://easyink.io` 
       - **Auth URL**: `https://identity.easyink.io/connect/authorize`
       - **Access Token URL**: `https://identity.easyink.io/connect/token`
       - **Client ID**: `{client-id}`
       - **Client Secret**: `{client-secret}`
       - **Code Challenge Method**: `S256`
       - **Scope**: `openid hermes_api hermes_idp profile`
    4. Click **Get New Access Token**.

    **Token properties:**
    - Format: JWT (JSON Web Token)
    - Expiration: Tokens expire after a set period (check `exp` claim)
    - Scopes: Tokens include scopes defining allowed operations
    - Refresh: Obtain new tokens before expiration

    ## Error Handling

    All error responses follow a consistent format using the ApiError model.
    Errors include:
    - Machine-readable error codes for programmatic handling
    - Human-readable error messages
    - Nested error details for validation failures

    **Common error codes:**
    - `ValidationError` - Invalid request data
    - `NotFound` - Resource does not exist
    - `Unauthorized` - Missing or invalid authentication
    - `Forbidden` - Insufficient permissions
    - `InternalServerError` - Server-side error
servers:
  - url: https://api-staging.easyink.io
    description: Staging server
  - url: https://api.easyink.io
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: SigningSessionDrafts
  - name: SigningSessions
paths:
  /api/signingSessionDrafts:
    post:
      tags:
        - SigningSessionDrafts
      summary: Create signing session draft
      description: |-
        Creates a new empty signing session draft that can be configured before sending to participants.

        **Typical workflow after creation:**
        1. Upload documents
        2. Add participants
        3. Add signature fields
        4. Optionally configure signing order
        5. Validate consistency
        6. Start the session to send to participants

        **What you get:**
        - Empty draft container with specified subject
        - Unique signing session ID for subsequent operations
        - Default settings from initiator's organization
      requestBody:
        required: true
        description: Basic information for creating the draft
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CreateDraft'
            examples:
              simple:
                summary: Create draft with subject only
                value:
                  subject: Employment Agreement - John Smith
              withInitiator:
                summary: Create draft with initiator settings
                value:
                  subject: Annual Review 2024
                  initiatorUser:
                    userId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                    organizationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    timestampFormat: Usa
      responses:
        '201':
          description: Draft created successfully
          content:
            application/json:
              schema:
                type: string
                format: uuid
              example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Subject cannot exceed 500 characters
      operationId: SigningSessionDrafts_Post
  /api/signingSessionDrafts/{signingSessionId}/documents:
    post:
      tags:
        - SigningSessionDrafts
      summary: Upload document to draft
      description: |-
        Uploads a document file and adds it as a document for signing to the session draft.

        **Supported formats:**
        - PDF (.pdf) - Recommended, no conversion needed
        - Microsoft Word (.docx, .doc) - Converted to PDF automatically

        **What happens:**
        1. File is uploaded to blob storage
        2. Document is converted to PDF (if needed)
        3. Document internal processing
        4. Document ID is returned for adding signature fields

        **File requirements:**
        - Maximum file size: typically 50 MB
        - Valid, non-corrupted file
        - Readable and processable format

        **After upload:**
        - Check document status (Processing → ProcessingReady)
        - Use returned ID to add signature fields to pages
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Document file to upload as multipart form data
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - fileContent
              properties:
                fileContent:
                  type: string
                  format: binary
                  description: Binary content of the PDF or Word document
            encoding:
              fileContent:
                contentType: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document
      responses:
        '201':
          description: Document uploaded and processing started
          content:
            application/json:
              schema:
                type: string
                format: uuid
              example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Provided file is not a valid PDF or DOC/DOCX document
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft with Id '115d5eef-0cc2-4619-b1b4-655cbb20cca5' does not exist
      operationId: SigningSessionDrafts_PostByIdDocuments
  /api/signingSessionDrafts/{id}/participants:
    post:
      tags:
        - SigningSessionDrafts
      summary: Add participant to draft
      description: |-
        Adds a new signer participant to a signing session draft.

        **Prerequisites:**
        - Draft session must exist
        - At least one delivery method (Email or Sms) must be specified
        - Corresponding contact information must be provided (email for Email, phone for Sms)

        **What happens:**
        1. Participant is added to the session with a unique ID
        2. Participant will receive signing invitation when the session is started
        3. Participant can be assigned to signature fields

        **Note:** This is for regular signing sessions. For bulk sessions, use the bulk participants endpoint.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Participant information including name, contact details, and delivery preferences
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/AddSigner'
            examples:
              emailParticipant:
                summary: Add participant with email delivery
                value:
                  firstName: John
                  middleName: null
                  lastName: Smith
                  email: john.smith@example.com
                  phone: null
                  deliveryMethods:
                    - Email
                  language: English
      responses:
        '201':
          description: Participant successfully added to the draft
          content:
            application/json:
              schema:
                type: string
                format: uuid
              example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                missingEmail:
                  summary: Email required when Email delivery method specified
                  value:
                    error:
                      code: ValidationError
                      message: Email address is required when Email delivery method is selected
                invalidPhone:
                  summary: Invalid phone number format
                  value:
                    error:
                      code: ValidationError
                      message: Phone number must be 10 digits (e.g., 2025551234)
      operationId: SigningSessionDrafts_PostByIdParticipants
  /api/signingSessionDrafts/{id}/signatureFields:
    post:
      tags:
        - SigningSessionDrafts
      summary: Add signature field to draft
      description: |-
        Adds a single signature field to a document in the signing session draft.

        **Prerequisites:**
        - Draft session must exist
        - Specified document must exist in the session
        - If participantId is provided, the participant must exist in the session
        - Field placement must be within document page boundaries

        **Typical workflow:**
        1. Create draft session
        2. Upload documents
        3. Add participants
        4. Add signature fields (this operation)
        5. Validate session consistency
        6. Start the session
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Signature field configuration including type, position, and options
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/AddSignatureField'
            examples:
              signatureField:
                summary: Add electronic signature field
                value:
                  participantId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                  documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  field:
                    type: Signature
                    placement:
                      page: 1
                      positionX: 100
                      positionY: 200
                      sizeX: 200
                      sizeY: 50
                    options:
                      isRequired: true
                      forType: Signature
              dateField:
                summary: Add date field
                value:
                  participantId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                  documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  field:
                    type: Date
                    placement:
                      page: 1
                      positionX: 320
                      positionY: 200
                      sizeX: 150
                      sizeY: 30
                    options:
                      isRequired: false
                      displayMode: Date
                      forType: Date
      responses:
        '201':
          description: Signature field created successfully
          content:
            application/json:
              schema:
                type: string
                format: uuid
              example: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                participantIdIsRequired:
                  summary: Participant Id is not provided
                  value:
                    error:
                      code: ValidationError
                      message: Participant Id for signature field is required
                documentNotFound:
                  summary: Participant Id provided for bulk session
                  value:
                    error:
                      code: ValidationError
                      message: For bulk session, all signature fields are common and cannot be tied to specific participant
      operationId: SigningSessionDrafts_PostByIdSignatureFields
  /api/signingSessionDrafts/{signingSessionId}/documents/{documentId}:
    get:
      tags:
        - SigningSessionDrafts
      summary: Download document PDF
      description: |-
        Downloads the complete document for signing in its original PDF format.

        **Use cases:**
        - Download document for offline review
        - Verify uploaded content before starting session
        - Extract document for external processing

        **Response:**
        - Content-Type: application/pdf
        - Original uploaded file (unmodified)
        - Binary PDF stream
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the document to download
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '200':
          description: PDF file stream of the document
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Suggested filename for download
              example: attachment; filename="Employment_Agreement.pdf"
            Content-Length:
              schema:
                type: integer
              description: Size of the PDF file in bytes
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Document processing is in progress. Try again later.
        '404':
          description: Document not found in this session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Can't find BLOB.
      operationId: SigningSessionDrafts_GetByIdDocumentsById
    delete:
      tags:
        - SigningSessionDrafts
      summary: Remove document from draft
      description: |-
        Removes a document for signing from the signing session draft.

        **Important:**
        - Document and all its pages are permanently deleted
        - All signature fields on this document are also removed
        - Cannot be undone
        - Can only be performed on draft sessions (not started sessions)

        **Use cases:**
        - Remove incorrect document
        - Replace document with corrected version
        - Simplify multi-document session

        **Cascade deletions:**
        - All signature fields assigned to this document
        - All page labels on this document
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the document to remove
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '204':
          description: Document removed successfully
      operationId: SigningSessionDrafts_DeleteByIdDocumentsById
  /api/signingSessionDrafts/{signingSessionId}/attachments/{attachmentId}:
    get:
      tags:
        - SigningSessionDrafts
      summary: Download attachment PDF
      description: |-
        Downloads the complete attachment document in PDF format.

        **Use cases:**
        - Download reference materials for offline review
        - Preview full attachment before starting session
        - Verify uploaded document content

        **Response:**
        - Content-Type: application/pdf
        - Binary PDF file stream
        - Original uploaded file (not modified)
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: attachmentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the attachment document
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '200':
          description: PDF file stream of the attachment
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Filename for download
              example: attachment; filename="Employee_Handbook.pdf"
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Document processing is in progress. Try again later.
        '404':
          description: Attachment not found in this session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Can't find BLOB.
      operationId: SigningSessionDrafts_GetByIdAttachmentsById
    delete:
      tags:
        - SigningSessionDrafts
      summary: Remove attachment from draft
      description: |-
        Removes an attachment document from the signing session draft.

        **Important:**
        - Only attachments can be removed, not documents for signing. To delete a document for signing, use the [Delete Document](/api-reference#tag/SigningSessionDrafts/operation/SigningSessionDrafts_DeleteByIdDocumentsById) endpoint.
        - Attachment and all its pages are permanently deleted
        - Cannot be undone
        - Can only be performed on draft sessions (not started sessions)

        **Use cases:**
        - Remove incorrect attachment
        - Replace attachment with updated version
        - Clean up unnecessary reference materials
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: attachmentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the attachment to remove
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '204':
          description: Attachment removed successfully
      operationId: SigningSessionDrafts_DeleteByIdAttachmentsById
  /api/signingSessionDrafts/{signingSessionId}/participants/me:
    post:
      tags:
        - SigningSessionDrafts
      summary: Add yourself as participant
      description: |-
        Adds the currently authenticated user as a participant to the signing session draft.

        **Convenience endpoint:**
        This is a shortcut for adding yourself without providing all your details.
        User information is automatically retrieved from your profile:
        - Name (first, middle, last)
        - Email address
        - Phone number (if available)
        - Language preference
        - Organization settings

        **Note:** This method does **not** set any delivery methods by default. To specify delivery methods (e.g., Email, SMS), you must use the [Update Participant](/api-reference#tag/SigningSessionDrafts/operation/SigningSessionDrafts_PutByIdParticipantsById) endpoint after adding yourself.

        **When to use:**
        - You are both initiator and signer
        - Self-signing scenarios (sign your own documents)
        - Testing and development

        **Automatic settings:**
        - Role: Initiator
        - Delivery methods: Based on available contact info
        - Language: From user profile
        - Pre-filled signature/initials: From saved preferences (if any)
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '201':
          description: Current user added as participant successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningConfigurationParticipant'
              example:
                id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                firstName: John
                middleName: Robert
                lastName: Smith
                email: john.smith@example.com
                phone: '2025551234'
                role: Signer
                userId: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                deliveryMethods:
                  - Email
                language: English
                signatureBlobId: null
                initialsBlobId: null
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Initiator already exists as a participant Smith, John
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_PostByIdParticipantsMe
  /api/signingSessionDrafts/{signingSessionId}/participants/{participantId}:
    put:
      tags:
        - SigningSessionDrafts
      summary: Update participant details
      description: |-
        Updates all information for an existing participant in the draft session.

        **What can be updated:**
        - Personal information (name)
        - Contact information (email, phone)
        - Delivery methods
        - Language preference

        **Important:**
        - This is a full update (all fields must be provided)
        - Partial updates are not supported
        - Can only update participants in draft sessions
        - Participant ID and role cannot be changed
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: participantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the participant to update
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
      requestBody:
        required: true
        description: Complete updated participant information
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/UpdateParticipant'
            examples:
              updateEmail:
                summary: Change participant's email address
                value:
                  firstName: John
                  middleName: Robert
                  lastName: Smith
                  email: john.smith@newcompany.com
                  phone: null
                  deliveryMethods:
                    - Email
                  language: English
              addPhoneNumber:
                summary: Add phone number and SMS delivery
                value:
                  firstName: John
                  middleName: Robert
                  lastName: Smith
                  email: john.smith@example.com
                  phone: '2025551234'
                  deliveryMethods:
                    - Email
                    - Sms
                  language: English
      responses:
        '204':
          description: Participant updated successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                participantIdIsRequired:
                  summary: Participant Id does not provided
                  value:
                    error:
                      code: ValidationError
                      message: Participant Id is required
                participantDoesNotExist:
                  summary: Participant with provided Id does not exist
                  value:
                    error:
                      code: ValidationError
                      message: Participant with id 'd0c86d56-cd71-4b7b-b62c-cd7f8dfd992c' does not exists
                unknownLanguage:
                  summary: Unknown language provided
                  value:
                    error:
                      code: ValidationError
                      message: Valid language is expected, but was French
                optedOutPhoneNumber:
                  summary: Phone number is opted out
                  value:
                    error:
                      code: ValidationError
                      message: Communication was rejected for phone number (202) 555-1234. The phone number should be re-opted in before it can be used.
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_PutByIdParticipantsById
    delete:
      tags:
        - SigningSessionDrafts
      summary: Remove participant from draft
      description: |-
        Removes a participant from the signing session draft.

        **Important:**
        - Participant is permanently removed
        - All signature fields assigned to this participant are also removed
        - Cannot be undone
        - Can only be performed on draft sessions (not started sessions)
        - Session must have at least one participant remaining

        **Use cases:**
        - Remove participant added by mistake
        - Replace participant with someone else
        - Reduce number of signers

        **Cascade deletions:**
        - All signature fields assigned to this participant
        - Participant's position in signing order (if sequential)
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: participantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the participant to remove
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
      responses:
        '204':
          description: Participant removed successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                participantIdIsRequired:
                  summary: Participant Id is required
                  value:
                    error:
                      code: ValidationError
                      message: Participant Id is required
                participantDoesNotExist:
                  summary: Participant does not exist
                  value:
                    error:
                      code: ValidationError
                      message: Participant with id '4d4b6681-aa0a-43a1-b0d3-63c39a49bfc8' does not exists
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_DeleteByIdParticipantsById
  /api/signingSessionDrafts/{id}/signingOrder/oneByOne:
    put:
      tags:
        - SigningSessionDrafts
      summary: Configure sequential signing order
      description: |-
        Sets up a one-by-one (sequential) signing order for participants in the draft session.

        **Sequential Signing Workflow:**
        1. First participant in the order receives invitation immediately
        2. After they complete signing, second participant receives invitation
        3. Process continues until all participants have signed

        **Use cases:**
        - Approval chains (employee → manager → HR)
        - Hierarchical signing (subordinate → supervisor → executive)
        - Sequential review (reviewer 1 → reviewer 2 → final approver)

        **Requirements:**
        - All participants in the session must be included in the order array
        - Order of participant IDs determines the signing sequence
        - Cannot be changed after session is started
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Ordered array of participant IDs defining the signing sequence
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SetOneByOneSigningOrder'
            examples:
              twoStep:
                summary: Two-step approval
                value:
                  participantsOrder:
                    - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                    - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
              approvalChain:
                summary: Four-level approval chain
                value:
                  participantsOrder:
                    - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                    - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                    - 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                    - 3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f
      responses:
        '204':
          description: Signing order configured successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                missingParticipant:
                  summary: Not all participants included
                  value:
                    error:
                      code: ValidationError
                      message: 'There are some participants missed in signing order definition: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d, 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e'
                duplicateParticipant:
                  summary: Unknown participant in the signing order
                  value:
                    error:
                      code: ValidationError
                      message: 'There are some non-existing participant ids defined in signing order definition: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d, 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e '
        404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: ../../definitions/API/v1/Core/Errors/ApiError.yaml
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_PutByIdSigningOrderOneByOne
  /api/signingSessionDrafts/{signingSessionId}/signingOrder/allAtOnce:
    put:
      tags:
        - SigningSessionDrafts
      summary: Enable parallel signing
      description: |-
        Configures the signing session for parallel (all-at-once) signing mode where
        all participants receive invitations simultaneously and can sign in any order.

        **Parallel Signing Behavior:**
        - All participants receive invitation emails at the same time
        - Participants can sign in any order
        - No waiting for previous participants to complete
        - Session completes when all participants have signed

        **Use cases:**
        - Multiple independent signers (no hierarchy)
        - Time-sensitive documents requiring quick completion
        - Peer agreements where order doesn't matter
        - Default mode for most signing sessions

        **Comparison with Sequential:**
        - Faster completion (no waiting)
        - Better for time-critical documents
        - Less control over signing sequence

        **This is the default mode** - only use this endpoint if you previously set one-by-one order
        and want to switch back to parallel mode.
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: Signing mode changed to parallel successfully
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_PutByIdSigningOrderAllAtOnce
  /api/signingSessionDrafts/{signingSessionId}/signatureFields/{signatureFieldId}:
    delete:
      tags:
        - SigningSessionDrafts
      summary: Remove signature field and all dependent fields
      description: |-
        Removes a signature field from the signing session draft.

        **Important cascade behavior:**
        This operation automatically removes all dependent fields as well.
        If other fields have `dependsOn` pointing to this field, they will also be deleted.

        **Example:**
        If you delete a signature field that has a date field depending on it,
        both the signature field AND the date field are removed.

        **Response:**
        Returns an array of all removed field IDs (the requested field plus any dependents).

        **Use cases:**
        - Remove incorrectly placed field
        - Clean up unused fields
        - Restructure field layout

        **Restrictions:**
        - Can only delete fields in draft sessions
        - Cannot be undone
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: signatureFieldId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signature field to remove
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '200':
          description: Field(s) removed successfully with list of all deleted field IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
              examples:
                singleField:
                  summary: Only the specified field was removed
                  value:
                    - 7c9e6679-7425-40de-944b-e07fc1f90ae7
                withDependents:
                  summary: Field and its dependent field were removed
                  value:
                    - 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Signature field with id 78765e33-b1f5-4339-bd1c-7bfbc294944b does not exists
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_DeleteByIdSignatureFieldsById
  /api/signingSessionDrafts/{signingSessionId}/signatureFields/{signatureFieldId}/options:
    put:
      tags:
        - SigningSessionDrafts
      summary: Update signature field options
      description: |-
        Updates the configuration options for an existing signature field in the draft.

        **What can be updated:**
        - Whether field is required (isRequired)
        - Type-specific options (displayMode for Date, fontSize for FreeText, etc.)

        **Important:**
        - Field type (forType) cannot be changed - it must match the existing field type
        - Can only update fields in draft sessions (not started sessions)
        - Options schema must match the field's type

        **Use cases:**
        - Change required status of a field
        - Adjust date display mode (Date → DateTime)
        - Modify text field formatting (font size, alignment)
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: signatureFieldId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signature field to update
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      requestBody:
        required: true
        description: Updated options (must match the field type)
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/Checkbox'
                - $ref: '#/components/schemas/Date'
                - $ref: '#/components/schemas/FreeText'
                - $ref: '#/components/schemas/FullName'
                - $ref: '#/components/schemas/Initials'
                - $ref: '#/components/schemas/Signature'
            examples:
              makeOptional:
                summary: Make signature field optional
                value:
                  isRequired: false
                  forType: Signature
              changeDateMode:
                summary: Change date field to DateTime mode
                value:
                  isRequired: true
                  displayMode: DateTime
                  forType: Date
              updateTextFormatting:
                summary: Update free text field formatting
                value:
                  isRequired: true
                  alignMode: Left
                  fontSize: 14
                  forType: FreeText
      responses:
        '204':
          description: Field options updated successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                typeMismatch:
                  summary: Options type doesn't match field type
                  value:
                    error:
                      code: ValidationError
                      message: Field options must target the field type
                dependedFieldNotRequired:
                  summary: Depended fields should not be required
                  value:
                    error:
                      code: ValidationError
                      message: Dependent field cannot be required
                fieldDoesNotExist:
                  summary: Signature field does not exist
                  value:
                    error:
                      code: ValidationError
                      message: Signature field with id 78765e33-b1f5-4339-bd1c-7bfbc294944b does not exists
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_PutByIdSignatureFieldsByIdOptions
  /api/signingSessionDrafts/{signingSessionId}/signatureFields/{signatureFieldId}/placement:
    put:
      tags:
        - SigningSessionDrafts
      summary: Update signature field placement
      description: |-
        Updates the position and size of a signature field on the document page.

        **Use cases:**
        - Reposition field to better location
        - Resize field for better visibility
        - Move field to different page
        - Adjust field to avoid overlap with document content

        **Requirements:**
        - Field must remain within page boundaries
        - New position must not create overlapping fields (validation depends on settings)
        - Can only update fields in draft sessions

        **Coordinate system reminder:**
        - Origin (0,0) is at bottom-left corner
        - X increases to the right
        - Y increases upward
        - All values in points (72 points = 1 inch)
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: signatureFieldId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signature field to reposition
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      requestBody:
        required: true
        description: New position and size for the signature field
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RectPlacement'
            examples:
              moveToTopRight:
                summary: Move field to top-right corner (A4)
                value:
                  page: 1
                  positionX: 395
                  positionY: 792
                  sizeX: 200
                  sizeY: 50
              moveToPage2:
                summary: Move field to second page
                value:
                  page: 2
                  positionX: 100
                  positionY: 200
                  sizeX: 200
                  sizeY: 50
              resizeLarger:
                summary: Make field larger
                value:
                  page: 1
                  positionX: 100
                  positionY: 200
                  sizeX: 300
                  sizeY: 75
      responses:
        '204':
          description: Field placement updated successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                positionXOutOfBounds:
                  summary: Position on X-axis is out of bounds
                  value:
                    error:
                      code: ValidationError
                      message: Position on X-axis cannot be less than 0
                positionYOutOfBounds:
                  summary: Position on Y-axis is out of bounds
                  value:
                    error:
                      code: ValidationError
                      message: Position on Y-axis cannot be less than 0
                sizeXOutOfBounds:
                  summary: Size on X-axis is out of bounds
                  value:
                    error:
                      code: ValidationError
                      message: X-axis size cannot be 0 or less
                sizeYOutOfBounds:
                  summary: Size on Y-axis is out of bounds
                  value:
                    error:
                      code: ValidationError
                      message: Y-axis size cannot be 0 or less
                fieldDoesNotExist:
                  summary: Signature field does not exist
                  value:
                    error:
                      code: ValidationError
                      message: Signature field with id 78765e33-b1f5-4339-bd1c-7bfbc294944b does not exists
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_PutByIdSignatureFieldsByIdPlacement
  /api/signingSessionDrafts/{signingSessionId}:
    head:
      tags:
        - SigningSessionDrafts
      summary: Check draft exists
      description: |-
        Checks whether a signing session draft exists without retrieving its full details.

        **Performance benefit:**
        Returns only HTTP status code without response body, making it faster and more
        lightweight than GET for existence checks.

        **Use cases:**
        - Validate draft ID before performing operations
        - Check if draft still exists before updates
        - Implement client-side caching with existence verification
        - Lightweight health check for draft availability

        **Response codes:**
        - 204: Draft exists
        - 404: Draft does not exist
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the draft session to check
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: Draft exists
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Draft does not exist
      operationId: SigningSessionDrafts_HeadById
    get:
      tags:
        - SigningSessionDrafts
      summary: Get draft details
      description: |-
        Retrieves complete details of a signing session draft including all documents,
        participants, signature fields, and configuration.

        **Returned information:**
        - Session metadata (ID, subject, status flags)
        - All documents with processing status
        - All attachments
        - All participants with contact info
        - All signature fields with placement and options
        - All page labels
        - Signing order settings
        - Reminder frequency

        **Use cases:**
        - Review draft configuration before starting
        - Check document processing status
        - Verify all participants and fields are configured
        - Get current state for UI display

        **Before starting the session:**
        Use this endpoint to verify the draft is complete and ready.
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Complete draft session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningSessionDraft'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Draft session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exist
      operationId: SigningSessionDrafts_GetById
    patch:
      tags:
        - SigningSessionDrafts
      summary: Update draft parameters
      description: |-
        Updates basic parameters of a signing session draft including subject and reminder settings.

        **What can be updated:**
        - Session subject/title shown to participants
        - Reminder frequency for automatic follow-ups

        **What cannot be updated via this endpoint:**
        - Documents (use document endpoints)
        - Participants (use participant endpoints)
        - Signature fields (use signature field endpoints)
        - Signing order (use signing order endpoint)

        **Use cases:**
        - Fix typo in subject line
        - Change reminder frequency based on urgency
        - Update subject to reflect participant name
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Updated session parameters
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SetSigningSessionParameters'
            examples:
              updateSubject:
                summary: Update session subject
                value:
                  subject: Employment Agreement - John Smith (Updated)
                  reminderFrequency: Daily
              disableReminders:
                summary: Disable automatic reminders
                value:
                  subject: Internal Document - No Rush
                  reminderFrequency: Never
              weeklyReminders:
                summary: Set weekly reminders
                value:
                  subject: Annual Review Agreement
                  reminderFrequency: Weekly
      responses:
        '204':
          description: Parameters updated successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Subject cannot exceed 500 characters
      operationId: SigningSessionDrafts_PatchById
    post:
      tags:
        - SigningSessionDrafts
      summary: Duplicate session as draft
      description: |-
        Creates a new draft by duplicating an existing signing session without voiding the original.

        **Use cases:**
        - Create similar agreements for different participants
        - Reuse template configuration for new session
        - Create periodic agreements (monthly, quarterly)
        - Test configuration before sending to real participants

        **What is copied:**
        - All documents
        - All participants
        - All signature field configurations
        - Session settings (subject, reminders, etc.)

        **What is NOT copied:**
        - Signatures (new draft starts fresh)
        - Session status (new draft is in Draft status)

        **After duplication:**
        1. Optionally modify documents or fields
        2. Start the new session

        **Original session:**
        Remains unchanged and can be in any status except Voided or Expired.
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the session to duplicate
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Optional custom subject for the new draft
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/DuplicateSigningSession'
            examples:
              customSubject:
                summary: Duplicate with new subject
                value:
                  subject: Q1 2025 Review Agreement
              defaultSubject:
                summary: Duplicate with auto-generated subject
                value:
                  subject: null
      responses:
        '201':
          description: New draft created successfully
          content:
            application/json:
              schema:
                type: string
                format: uuid
              example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                cannotDuplicate:
                  summary: Session cannot be duplicated
                  value:
                    error:
                      code: ValidationError
                      message: 'Signing session should not be in following statuses: Voided, Expired, Finished'
                copyDisabled:
                  summary: Session copying disabled by policy
                  value:
                    error:
                      code: ValidationError
                      message: Signing session copy is not allowed
        '404':
          description: Original session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
      operationId: SigningSessionDrafts_PostById
    delete:
      tags:
        - SigningSessionDrafts
      summary: Delete draft session
      description: |-
        Permanently deletes a signing session draft and all associated data.

        **What is deleted:**
        - The draft session itself
        - All documents and their pages
        - All attachments
        - All participants
        - All signature fields
        - All page labels
        - All uploaded blobs (document files)

        **Important:**
        - This operation is permanent and cannot be undone
        - Can only delete drafts (not started sessions)
        - All associated files are removed from storage

        **Use cases:**
        - Cancel draft creation
        - Clean up test drafts
        - Remove obsolete draft sessions

        **To cancel a started session:** Use the void operation instead of delete.
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the draft session to delete
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: Draft deleted successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Signing session draft is locked and cannot be removed
        '404':
          description: Signing session draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exists
      operationId: SigningSessionDrafts_DeleteById
  /api/signingSessionDrafts/{signingSessionId}/sourceVoided:
    post:
      tags:
        - SigningSessionDrafts
      summary: Recreate session with void
      description: |-
        Creates a new draft by copying an existing signing session, then voids the original session.

        **Atomic operation:**
        1. Creates new draft with same configuration (documents, participants, fields)
        2. Voids the original session with provided reason
        3. Returns new draft ID for further configuration

        **Use cases:**
        - Document has errors and needs correction (recreate with fixes)
        - Session was declined and needs to be resent with changes
        - Terms changed after session started

        **What is copied:**
        - All documents
        - All participants
        - All signature field configurations
        - Session settings (subject, reminders, etc.)

        **What is NOT copied:**
        - Existing signatures (new draft starts fresh)
        - Session status (new draft is in Draft status)
        - Signed documents

        **Requirements:**
        - Original session must be in InProgress or Declined status
        - Void reason is mandatory
        - User must have permission to void original session
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the session to recreate and void
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Optional new subject and mandatory void reason
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RecreateSigningSession'
            examples:
              withNewSubject:
                summary: Recreate with updated subject
                value:
                  subject: Employment Agreement - Corrected Version
                  voidReason: Original document contained incorrect salary information
              keepSubject:
                summary: Recreate with same subject
                value:
                  subject: null
                  voidReason: Participant requested changes to signing deadline
      responses:
        '201':
          description: New draft created and original session voided successfully
          content:
            application/json:
              schema:
                type: string
                format: uuid
              example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalidStatus:
                  summary: Session not in recreatable status
                  value:
                    error:
                      code: ValidationError
                      message: 'Signing session has status ''ReadyToStart'', but must be in one of following statuses: InProgress, Declined'
                isCopyDisabled:
                  summary: Void reason is required
                  value:
                    error:
                      code: ValidationError
                      message: Signing session copy is not allowed
        '404':
          description: Original session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
      operationId: SigningSessionDrafts_PostByIdSourceVoided
  /api/signingSessions/{signingSessionId}:
    head:
      tags:
        - SigningSessions
      summary: Check session exists
      description: |-
        Lightweight check for signing session existence without retrieving full details.

        **Performance benefit:**
        - No response body (only HTTP status)
        - Faster than GET operation
        - Minimal server processing
        - Reduced bandwidth usage

        **Use cases:**
        - Validate session ID before operations
        - Implement client-side caching with validation
        - Quick health check for session availability

        **Response interpretation:**
        - 204: Session exists
        - 404: Session does not exist
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: Session exists
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Session does not exist
      operationId: SigningSessions_HeadById
    get:
      tags:
        - SigningSessions
      summary: Get session details
      description: |-
        Retrieves complete details of an active or completed signing session including
        all documents, participants, status, and signed document availability.

        **Returned information:**
        - Session metadata (ID, subject, status)
        - Permission flags (canBeVoided, canBeCopied)
        - All documents (original documents list)
        - All participants with signing status and timestamps
        - All signed documents (participant-specific signed copies)
        - All attachments (reference materials)
        - All-in-one document availability

        **Use cases:**
        - Monitor session progress
        - Check participant signing status
        - Download signed documents
        - Display session details in UI
        - Track completion percentage

        **Performance note:**
        This endpoint returns complete session data. For lightweight existence checks,
        use the HEAD operation instead.
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Complete signing session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningSession'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Signing session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session does not exist
      operationId: SigningSessions_GetById
    post:
      tags:
        - SigningSessions
      summary: Convert draft to ready session
      description: |-
        Converts a draft signing session to ReadyToStart status, making it ready to send to participants.

        **What this operation does:**
        - Validates draft configuration
        - Transitions status from Draft to ReadyToStart
        - Locks the session from further structural changes
        - Draft is effectively converted to an active session (but not yet sent)

        **Prerequisites:**
        - Draft must have complete configuration
        - All documents must be ProcessingReady
        - All required fields must be present
        - Configuration must pass validation

        **After conversion:**
        - Use the "Start" endpoint to send invitations to participants
        - Session cannot be converted back to draft
        - Can still be deleted or voided if needed

        **Typical flow:**
        1. Create draft
        2. Configure (documents, participants, fields)
        3. Convert to ready (this operation)
        4. Start sending to participants
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the draft session to convert
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: Session converted to ReadyToStart status successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalidConfiguration:
                  summary: Configuration incomplete
                  value:
                    error:
                      code: ValidationError
                      message: Session configuration is invalid. Check that all documents, participants, and fields are configured.
                notDraft:
                  summary: Session not in draft status
                  value:
                    error:
                      code: ValidationError
                      message: Only draft sessions can be converted to ready status
        '404':
          description: Draft session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session draft does not exist
      operationId: SigningSessions_PostById
  /api/signingSessions/{signingSessionId}/started:
    post:
      tags:
        - SigningSessions
      summary: Start sending to participants
      description: |-
        Initiates the signing session by sending invitations to participants.
        This transitions the session from ReadyToStart to InProgress/Pending status.

        **Prerequisites - session must have:**
        - At least one document with ProcessingReady status
        - At least one participant with valid contact information
        - At least one signature field configured
        - Valid configuration (passes consistency validation)

        **What happens:**
        1. Session status changes to InProgress
        2. Signing invitations sent to participants via configured delivery methods:
           - Sequential mode: Only first participant receives invitation
           - Parallel mode: All participants receive invitations simultaneously
        3. Participants receive emails/SMS with unique signing links
        4. Session becomes unavailable for changes
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session to start
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: Session started successfully and invitations sent
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                noDocuments:
                  summary: No documents configured
                  value:
                    error:
                      code: ValidationError
                      message: Session must have at least one document before starting
                noParticipants:
                  summary: No participants configured
                  value:
                    error:
                      code: ValidationError
                      message: Session must have at least one participant before starting
                documentsProcessing:
                  summary: Documents still processing
                  value:
                    error:
                      code: ValidationError
                      message: Cannot start session while documents are being processed
                alreadyStarted:
                  summary: Session already started
                  value:
                    error:
                      code: ValidationError
                      message: Session has already been started
        '404':
          description: Signing session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session does not exist
      operationId: SigningSessions_PostByIdStarted
  /api/signingSessions/{signingSessionId}/participants/{participantId}:
    put:
      tags:
        - SigningSessions
      summary: Update participant contact info
      description: |-
        Updates delivery methods and contact information for a participant in an active signing session.

        **When to use:**
        - Participant's email changed
        - Participant didn't receive invitation (wrong contact info)
        - Need to add SMS delivery method
        - Participant requests different contact method

        **Important restrictions:**
        - Can only update participants in Pending or Activated status
        - Cannot update after participant opened the signing link
        - New invitation will be sent to updated contact information
        - Access token will be regenerated for security

        **What happens:**
        1. Contact information is updated
        2. New access token is generated
        3. Fresh invitation is sent via new delivery methods
        4. Old invitation link becomes invalid
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: participantId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the participant to update
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
      requestBody:
        required: true
        description: Updated delivery methods and contact information
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/UpdateParticipantDeliveryMethods'
            examples:
              changeToEmail:
                summary: Change from SMS to Email delivery
                value:
                  deliveryMethods:
                    - Email
                  email: participant@newcompany.com
                  phone: null
              addSmsMethod:
                summary: Add SMS as additional delivery method
                value:
                  deliveryMethods:
                    - Email
                    - Sms
                  email: participant@example.com
                  phone: '2025559999'
      responses:
        '204':
          description: Delivery methods updated and new invitation sent
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                alreadyUsedLink:
                  summary: Cannot update after link used
                  value:
                    error:
                      code: ValidationError
                      message: Delivery method can't be changed because the participant has already used the signing link
                notAllowedInSessionStatus:
                  summary: Cannot update in this session status
                  value:
                    error:
                      code: ValidationError
                      message: 'Cannot update participant delivery methods: current signing session status ''Expired'' is not allows to it'
                notAllowedInFinishedSession:
                  summary: Cannot update in finished session
                  value:
                    error:
                      code: ValidationError
                      message: 'Cannot update participant delivery methods: participant has already completed the signing.'
                invalidEmail:
                  summary: Invalid email format
                  value:
                    error:
                      code: ValidationError
                      message: Email address format is invalid
                phoneOptedOut:
                  summary: Phone number opted out
                  value:
                    error:
                      code: ValidationError
                      message: Communication was rejected for phone number. 2025559999
        '404':
          description: Signing session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
      operationId: SigningSessions_PutByIdParticipantsById
  /api/signingSessions/{signingSessionId}/attachments/{attachmentId}:
    get:
      tags:
        - SigningSessions
      summary: Download attachment
      description: |-
        Downloads an attachment document from an active or completed signing session.

        **Attachments vs Documents:**
        - Attachments are reference materials (not signed)
        - Remain unchanged throughout session
        - Available to all participants for viewing
        - Original uploaded file (no signatures added)

        **Use cases:**
        - Download supporting documentation
        - Review reference materials
        - Access policy documents
        - Retrieve background information

        **Availability:**
        Available in all session statuses except Draft.
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: attachmentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the attachment to download
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '200':
          description: Attachment PDF file
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Suggested filename for download
              example: attachment; filename="Company_Policy_Handbook.pdf"
            Content-Type:
              schema:
                type: string
              example: application/pdf
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Attachment '7c9e6679-7425-40de-944b-e07fc1f90ae7' not found
        '404':
          description: Session or attachment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                sessionNotFound:
                  summary: Session doesn't exist
                  value:
                    error:
                      code: NotFound
                      message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
                attachmentNotFound:
                  summary: Attachment not found
                  value:
                    error:
                      code: NotFound
                      message: Can't find BLOB.
      operationId: SigningSessions_GetByIdAttachmentsById
  /api/signingSessions/{signingSessionId}/documents/{documentId}:
    get:
      tags:
        - SigningSessions
      summary: Download original document
      description: |-
        Downloads the original document for signing from a signing session in PDF format.

        **Important:**
        This returns the ORIGINAL document without any signatures applied.
        For signed documents with signatures, use the signed documents endpoint.

        **Use cases:**
        - Review original document content
        - Compare original vs signed version
        - Access document before all signatures collected
        - Download for printing or offline review

        **Document state:**
        - Original uploaded file
        - No signatures or modifications
        - Same as what was uploaded to draft

        **For signed versions:**
        - Use GET /api/signingSessions/{id}/signedDocuments/{signedDocumentId}
        - Or GET /api/signingSessions/{id}/allInOne for complete package
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the document to download
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '200':
          description: Original document PDF file (without signatures)
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Suggested filename
              example: attachment; filename="Employment_Agreement_Original.pdf"
            Content-Type:
              schema:
                type: string
              example: application/pdf
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: ValidationError
                  message: Document '7c9e6679-7425-40de-944b-e07fc1f90ae7' not found
        '404':
          description: Session or document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                sessionNotFound:
                  summary: Session doesn't exist
                  value:
                    error:
                      code: NotFound
                      message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
                documentNotFound:
                  summary: Document not found
                  value:
                    error:
                      code: NotFound
                      message: Can't find BLOB.
      operationId: SigningSessions_GetByIdDocumentsById
  /api/signingSessions/{id}/voided:
    post:
      tags:
        - SigningSessions
      summary: Void active session
      description: |-
        Voids (cancels/annuls) an active signing session, preventing any further actions.

        **What happens:**
        - Session status changes to Voided
        - No more signatures can be collected
        - Session cannot be reactivated

        **When to use:**
        - Document contains errors
        - Terms have changed
        - Participant requested cancellation
        - Session no longer needed

        **Alternative:**
        Consider using "Recreate" instead if you need a corrected version.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session to void
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        description: Void reason
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/VoidSigningSession'
            examples:
              void:
                summary: Void session with reason
                value:
                  reason: Document contained incorrect information
      responses:
        '204':
          description: Session voided successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                missingReason:
                  summary: Void reason is required
                  value:
                    error:
                      code: ValidationError
                      message: Voiding reason is required
                alreadyVoided:
                  summary: Session already voided
                  value:
                    error:
                      code: ValidationError
                      message: Signing is already voided
                voidDisabled:
                  summary: Void operation disabled by policy
                  value:
                    error:
                      code: ValidationError
                      message: Signing session cannot be voided, since void is disabled
        '404':
          description: Signing session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: NotFound
                  message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
      operationId: SigningSessions_PostByIdVoided
  /api/signingSessions:
    get:
      tags:
        - SigningSessions
      summary: Search signing sessions
      description: |-
        Search and filter signing sessions with pagination and sorting support.

        Returns a paginated list of signing sessions matching the specified criteria.
        Results can be filtered by status and sorted by multiple properties.

        **Use cases:**
        - Get all signing sessions awaiting signatures
        - Find sessions that need current user's action
        - Retrieve completed sessions
        - Monitor session statuses
      parameters:
        - name: statuses
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - Draft
                - ReadyToStart
                - InProgress
                - NeedToSign
                - Finished
                - Declined
                - Voided
                - Expired
                - NeedsAction
          description: |-
            Filter signing sessions by status. Multiple statuses can be specified.

            Status values:
            - `Draft` - Session is being configured
            - `ReadyToStart` - Ready to be sent to participants
            - `InProgress` - Sent to participants, awaiting signatures
            - `NeedToSign` - Current user needs to sign
            - `Finished` - All participants have signed
            - `Declined` - A participant declined to sign
            - `Voided` - Session was cancelled/voided
            - `Expired` - Session expired before completion
            - `NeedsAction` - Requires user action
          example:
            - InProgress
            - NeedToSign
        - name: pageIndex
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Zero-based page index for pagination (0 = first page)
          example: 0
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of items to return per page (max 100)
          example: 20
        - name: sorting.properties
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PropertySorting'
          description: |-
            Array of sorting rules applied in order of priority.

            Example: To sort by status ascending, then by creation date descending:
            `?sorting.properties[0].name=status&sorting.properties[0].direction=Ascending&sorting.properties[1].name=created&sorting.properties[1].direction=Descending`
          example:
            - name: created
              direction: Descending
            - name: subject
              direction: Ascending
      responses:
        '200':
          description: Signing sessions search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSigningSessionsResult'
      operationId: SigningSessions_Get
  /api/signingSessions/summary:
    get:
      tags:
        - SigningSessions
      summary: Get sessions statistics
      description: |-
        Retrieves summary statistics about signing sessions grouped by status for the current user.

        **Returned statistics:**
        - Sessions requiring user's signature
        - Draft sessions created by user
        - Sessions ready to start
        - Sessions in progress
        - Sessions needing attention

        **Use cases:**
        - Dashboard widgets showing session counts
        - Overview/home screen statistics
        - Quick status summary without fetching all sessions
        - Notification badge counts (e.g., "5 sessions to sign")   

        **Scope:**
        Only includes sessions visible to the authenticated user based on:
        - Sessions they created
        - Sessions where they are a participant
        - Organization access permissions
      responses:
        '200':
          description: Summary statistics for user's signing sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSigningSessionsSummaryResult'
              example:
                sessionsToSignCount: 3
                draftsCount: 5
                readyToStartCount: 2
                inProgressCount: 12
                needsActionCount: 1
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: SigningSessions_GetSummary
  /api/signingSessions/{signingSessionId}/signedDocuments/{documentId}:
    get:
      tags:
        - SigningSessions
      summary: Download signed document
      description: |-
        Downloads a completed signed document with signatures applied for a specific participant.

        **What's included:**
        - Original document pages
        - All signature fields filled by the participant
        - Participant's signatures, initials, dates, etc.

        **Availability:**
        - Only after participant completes signing (status: Signed)
        - Document must be in ProcessingReady status

        **Use cases:**
        - Download participant's signed copy
        - Provide signed document to participant
        - Archive individual signed agreements
        - Legal compliance and record keeping
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the signed document
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '200':
          description: Signed document PDF with signatures and audit trail
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Suggested filename including participant name
              example: attachment; filename="Employment_Agreement_John_Smith_Signed.pdf"
            Content-Type:
              schema:
                type: string
              example: application/pdf
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                notSigned:
                  summary: Participant hasn't signed yet
                  value:
                    error:
                      code: ValidationError
                      message: Signed document is not available until participant completes signing
                stillProcessing:
                  summary: Document generation in progress
                  value:
                    error:
                      code: ValidationError
                      message: Signed document is being generated. Please try again shortly.
        '404':
          description: Session or signed document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                sessionNotFound:
                  summary: Session doesn't exist
                  value:
                    error:
                      code: NotFound
                      message: Signing session does not exist
                documentNotFound:
                  summary: Signed document not found
                  value:
                    error:
                      code: NotFound
                      message: Can't find BLOB.
      operationId: SigningSessions_GetByIdSignedDocumentsById
  /api/signingSessions/{signingSessionId}/allInOne:
    get:
      tags:
        - SigningSessions
      summary: Download all-in-one document
      description: |-
        Downloads a combined PDF containing all signed documents from all participants
        with complete audit trail information.

        **Document contents (in order):**
        1. Cover page with session summary
        2. All original documents with signatures applied
        3. Detailed audit trail for each signature:
           - Participant name and email
           - Signing timestamp
           - IP address
           - Authentication method
           - Legal disclosures

        **Availability:**
        - Only available after session status is Finished
        - Document generation may take time for large sessions
        - Check allInOneDocument.status before downloading

        **Use cases:**
        - Archive complete signed agreement
        - Submit to legal/compliance
        - Provide all parties with complete record
        - Long-term storage with full audit trail

        **File characteristics:**
        - Size: Larger than individual signed documents
        - Includes all participants' signatures
      parameters:
        - name: signingSessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the completed signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Complete all-in-one PDF with signatures and audit trail
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Filename for the combined document
              example: attachment; filename="Employment_Agreement_All_Signatures.pdf"
            Content-Type:
              schema:
                type: string
              example: application/pdf
            Content-Length:
              schema:
                type: integer
              description: File size in bytes
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                compilationFailed:
                  summary: Document compilation failed
                  value:
                    error:
                      code: ValidationError
                      message: All-in-one document compilation failed.
                stillGenerating:
                  summary: Document generation in progress
                  value:
                    error:
                      code: ValidationError
                      message: All-in-one document is not ready yet. Try again later.
        '404':
          description: Session or document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                sessionNotFound:
                  summary: Session doesn't exist
                  value:
                    error:
                      code: NotFound
                      message: Signing session '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found
                documentNotReady:
                  summary: All-in-one document not generated
                  value:
                    error:
                      code: NotFound
                      message: Can't find BLOB.
      operationId: SigningSessions_GetByIdAllInOne
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the authentication service
  schemas:
    ApiError:
      type: object
      description: Standard error response wrapper returned by the API for all error scenarios
      properties:
        error:
          description: Error details containing error code, message and optional nested errors
          anyOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/FullExceptionError'
          type: object
      example:
        error:
          code: ValidationError
          message: Validation failed for one or more fields
          innerErrors:
            - code: RequiredField
              message: The 'email' field is required
    Error:
      type: object
      description: Represents an error with a code, human-readable message, and optional nested errors
      properties:
        code:
          type: string
          nullable: true
          description: Machine-readable error code for programmatic error handling
          example: ValidationError
        message:
          type: string
          nullable: true
          description: Human-readable error message describing what went wrong
          example: The email address is not valid
        innerErrors:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/FullExceptionError'
          nullable: true
          description: Nested errors providing additional details about the failure (e.g., validation errors for specific fields)
      example:
        code: ValidationError
        message: Request validation failed
        innerErrors:
          - code: RequiredField
            message: The 'email' field is required
          - code: InvalidFormat
            message: The 'phoneNumber' format is invalid
    FullExceptionError:
      type: object
      description: Extended error information including exception details and stack trace (only available in development mode)
      allOf:
        - $ref: '#/components/schemas/Error'
      properties:
        exceptionType:
          type: string
          nullable: true
          description: Full type name of the exception that occurred
          example: System.ArgumentNullException
        stackTrace:
          type: array
          items:
            type: string
          nullable: true
          description: Stack trace lines showing where the exception occurred (development mode only)
          example:
            - at Confie.Hermes.Applications.API.Controllers.SigningSessionsController.GetById(Guid id)
            - at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.Invoke()
    DuplicateSigningSession:
      type: object
      description: Request to duplicate an existing signing session, creating a new draft with the same configuration
      properties:
        subject:
          type: string
          nullable: true
          description: Optional custom subject/title for the duplicated signing session
          maxLength: 500
          example: Contract Agreement - Copy
      example:
        subject: Annual Review Document - Revised Version
    RecreateSigningSession:
      type: object
      description: Request to recreate a signing session that is in progress or declined, voiding the original and creating a new draft
      properties:
        subject:
          type: string
          nullable: true
          description: Optional custom subject/title for the recreated signing session
          maxLength: 500
          example: Contract Agreement - Corrected Version
        voidReason:
          type: string
          nullable: true
          description: Reason for voiding the original signing session (required when recreating)
          minLength: 1
          maxLength: 1000
          example: Document contained errors and needs to be corrected
      example:
        subject: Employment Contract - Updated Terms
        voidReason: Incorrect salary information in the original document
    PropertySorting:
      type: object
      description: Defines sorting criteria for a single property in collection queries. Multiple sorting rules can be applied in order of priority.
      properties:
        name:
          type: string
          nullable: true
          description: |-
            Property name to sort by. Only properties marked with [Sortable] attribute are supported.

            Common sortable properties:
            - `subject` - Signing session subject/title
            - `created` - Creation timestamp
            - `status` - Current status of the signing session
          example: created
        direction:
          type: string
          enum:
            - Ascending
            - Descending
          description: |-
            Sort order direction:
            - `Ascending` - Sort from smallest to largest (A-Z, 0-9, oldest to newest)
            - `Descending` - Sort from largest to smallest (Z-A, 9-0, newest to oldest)
          default: Ascending
          example: Descending
      x-examples:
        sortByCreatedDesc:
          summary: Sort by creation date (newest first)
          value:
            name: created
            direction: Descending
        sortBySubjectAsc:
          summary: Sort by subject alphabetically
          value:
            name: subject
            direction: Ascending
        sortByStatus:
          summary: Sort by status
          value:
            name: status
            direction: Ascending
    CreateDraft:
      type: object
      description: |-
        Request to create a new signing session draft. A draft is an empty container where you can 
        add documents, participants, and signature fields before sending the session for signing.

        Workflow:
        1. Create draft with subject and initiator info
        2. Upload documents
        3. Add participants
        4. Add signature fields to documents
        5. Start the signing session
      properties:
        subject:
          type: string
          nullable: true
          description: |-
            Subject/title of the signing session shown to participants in emails and the signing interface.
            Should clearly identify the purpose of the signing (e.g., "Employment Contract - John Smith").
          maxLength: 500
          example: Employment Agreement - Q4 2024
        initiatorUser:
          allOf:
            - $ref: '#/components/schemas/InitiatorUser'
          type: object
          nullable: true
          description: |-
            Information about the user creating the draft and their preferences.
            If not provided, defaults to the authenticated user's settings.
      example:
        subject: Annual Review Agreement 2024
        initiatorUser:
          userId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
          organizationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          timestampFormat: Usa
    SigningConfigurationAttachment:
      type: object
      description: |-
        Represents an attachment document in a signing session draft. Unlike documents for signing, 
        attachments are reference materials that participants can view but do not contain 
        signature fields. This documents can have pre-signed pages.

        Common use cases:
        - Supporting documentation (policies, terms)
        - Reference materials (specifications, instructions)
        - Background information (company info, disclosures)
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the attachment
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title:
          type: string
          nullable: true
          description: Display name of the attachment shown to participants
          maxLength: 500
          example: Company Policy Document
        blobId:
          type: string
          format: uuid
          description: Reference to the PDF file in blob storage
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        status:
          type: string
          enum:
            - Processing
            - ProcessingReady
            - ProcessingFailed
          description: |-
            Processing status of the attachment:
            - `Processing` - File is being processed and converted to PDF pages
            - `ProcessingReady` - File is ready to be viewed by participants
            - `ProcessingFailed` - Processing failed, file may be corrupt or invalid format
          example: ProcessingReady
        pages:
          type: array
          items:
            $ref: '#/components/schemas/DocumentPage'
          nullable: true
          description: Array of rendered pages from the attachment PDF
      example:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title: Employee Handbook
        blobId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        status: ProcessingReady
        pages:
          - blobId: a1b2c3d4-5678-90ab-cdef-1234567890ab
            number: 1
            width: 595
            height: 842
    BulkParticipant:
      type: object
      description: |-
        Represents a participant in a bulk signing session. Bulk participants are typically added
        from CSV files or spreadsheets and share the same document configuration.

        Each bulk participant receives their own signing link and signs an identical copy of the document.
      allOf:
        - $ref: '#/components/schemas/ParticipantBase'
      properties:
        email:
          type: string
          nullable: true
          description: Email address where the signing invitation will be sent
          format: email
          maxLength: 256
          example: participant@example.com
      example:
        id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        firstName: John
        middleName: Robert
        lastName: Smith
        email: john.smith@example.com
    InitiatorUser:
      type: object
      description: |-
        Information about the user who initiated the signing session and their organization settings.
        This determines default behaviors like timestamp formats in generated documents.
      properties:
        userId:
          type: string
          format: uuid
          description: Unique identifier of the user who created the signing session
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        organizationId:
          type: string
          format: uuid
          description: Organization ID to which the initiator belongs, affecting default settings and permissions
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        timestampFormat:
          type: string
          enum:
            - Usa
            - Spanish
          description: |-
            Preferred timestamp format for displaying dates in the signing session:
            - `Usa` - US format (MM/DD/YYYY hh:mm AM/PM)
            - `Spanish` - European format (DD/MM/YYYY HH:mm)
          default: Usa
          example: Usa
      example:
        userId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        organizationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        timestampFormat: Usa
    SigningConfigurationDocument:
      type: object
      description: |-
        Represents a document for signing in a signing session draft. Documents for signing are the 
        documents that participants will sign and can contain signature fields.

        Multiple documents can be included in a single signing session, and participants 
        will sign all of them in sequence.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the document within the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title:
          type: string
          nullable: true
          description: Display name of the document shown to participants during signing
          maxLength: 500
          example: Employment Agreement
        blobId:
          type: string
          format: uuid
          description: Reference to the uploaded PDF file in blob storage
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        status:
          type: string
          enum:
            - Processing
            - ProcessingReady
            - ProcessingFailed
          description: |-
            Processing status of the document:
            - `Processing` - PDF is being processed and split into pages
            - `ProcessingReady` - Document is ready and can be sent to participants
            - `ProcessingFailed` - Processing failed (invalid PDF, corrupted file, unsupported format)
          example: ProcessingReady
        pages:
          type: array
          items:
            $ref: '#/components/schemas/DocumentPage'
          nullable: true
          description: Rendered pages from the PDF with dimensions for signature field placement
      example:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title: Employment Agreement
        blobId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        status: ProcessingReady
        pages:
          - blobId: a1b2c3d4-5678-90ab-cdef-1234567890ab
            number: 1
            width: 595
            height: 842
          - blobId: b2c3d4e5-6789-01bc-def0-2345678901bc
            number: 2
            width: 595
            height: 842
    PageLabel:
      type: object
      description: |-
        Defines a text label to be rendered on document pages, typically used for adding 
        metadata like signing session IDs, timestamps, or tracking numbers to signed documents.

        Page labels are automatically filled with dynamic content and can be placed on 
        multiple pages in the same positions.
      required:
        - contentType
        - documentId
        - id
        - options
        - placements
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the page label
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        documentId:
          type: string
          format: uuid
          description: ID of the document where this label will be rendered
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        placements:
          type: array
          items:
            $ref: '#/components/schemas/RectPlacement'
          nullable: true
          description: |-
            Array of rectangular areas where the label will be rendered.
            Can be placed on multiple pages or multiple times on the same page.
        options:
          allOf:
            - $ref: '#/components/schemas/PageLabelOptions'
          type: object
          description: Formatting options for the label (font size, weight, padding)
        contentType:
          type: string
          enum:
            - SigningSessionId
          description: |-
            Type of dynamic content to display in the label:
            - `SigningSessionId` - Displays the signing session's unique identifier
          example: SigningSessionId
        preview:
          type: string
          nullable: true
          description: Preview text showing what the label will look like when rendered
          readOnly: true
          example: 'Session ID: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
      example:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        placements:
          - page: 1
            positionX: 50
            positionY: 50
            sizeX: 300
            sizeY: 20
        options:
          fontSize: 10
          fontWeight: Normal
          paddingX: 5
          paddingY: 2
        contentType: SigningSessionId
        preview: 'Session ID: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
    SigningConfigurationParticipant:
      type: object
      description: |-
        Represents a participant in a regular (non-bulk) signing session with their contact 
        information, role, and delivery preferences.

        Participants can be signers (who sign documents) or initiators (who created the session).
        Each participant receives personalized notifications and can have pre-configured signatures.
      allOf:
        - $ref: '#/components/schemas/ParticipantBase'
      properties:
        email:
          type: string
          nullable: true
          description: Email address for sending signing invitations and notifications
          format: email
          maxLength: 256
          example: participant@example.com
        phone:
          type: string
          nullable: true
          description: Phone number for SMS notifications (10 digits)
          pattern: ^\d{10}$
          example: '2025551234'
        role:
          type: string
          enum:
            - Initiator
            - Signer
          description: |-
            Role of the participant in the signing session:
            - `Initiator` - User who created the signing session (can be a signer too)
            - `Signer` - Participant who needs to sign the document
          example: Signer
        userId:
          type: string
          format: uuid
          nullable: true
          description: |-
            Optional link to a registered user account in the system.
            If specified, pre-fills participant information from their profile.
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        deliveryMethods:
          type: array
          items:
            type: string
            enum:
              - Email
              - Sms
          nullable: true
          description: |-
            Methods for delivering the signing link to the participant.
            Multiple methods can be specified for redundancy.
          example:
            - Email
        language:
          type: string
          enum:
            - English
            - Spanish
          description: Preferred language for notifications and the signing interface
          default: English
          example: English
        signatureBlobId:
          type: string
          format: uuid
          nullable: true
          description: |-
            Optional reference to a pre-saved signature image blob.
            If provided, this signature can be automatically applied to signature fields.
          example: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        initialsBlobId:
          type: string
          format: uuid
          nullable: true
          description: |-
            Optional reference to a pre-saved initials image blob.
            If provided, these initials can be automatically applied to initial fields.
          example: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
      example:
        id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        firstName: Jane
        middleName: Marie
        lastName: Johnson
        email: jane.johnson@example.com
        phone: '2025551234'
        role: Signer
        userId: null
        deliveryMethods:
          - Email
          - Sms
        language: English
        signatureBlobId: null
        initialsBlobId: null
    ParticipantBase:
      type: object
      description: |-
        Base participant information containing personal details. This is extended by specific 
        participant types (e.g., BulkParticipant) that add delivery method information.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier of the participant in the signing session
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        firstName:
          type: string
          nullable: true
          readOnly: true
          description: Participant's first (given) name
          maxLength: 100
          example: John
        middleName:
          type: string
          nullable: true
          readOnly: true
          description: Participant's middle name or initial (optional)
          maxLength: 100
          example: Robert
        lastName:
          type: string
          nullable: true
          readOnly: true
          description: Participant's last (family) name
          maxLength: 100
          example: Smith
      example:
        id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        firstName: John
        middleName: Robert
        lastName: Smith
    SignatureField:
      type: object
      description: |-
        Configuration for a signature field in a draft signing session.
        Defines where and how participants will interact with the document.

        Signature fields are the primary mechanism for collecting information from participants,
        including signatures, dates, initials, and custom data.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the signature field within the draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        documentId:
          type: string
          format: uuid
          description: ID of the document where this field will be placed
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        participantId:
          type: string
          format: uuid
          nullable: true
          description: ID of the specific participant assigned to fill this field.
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        placement:
          allOf:
            - $ref: '#/components/schemas/RectPlacement'
          type: object
          description: Position and size of the field on the document page
        type:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          description: |-
            Type of signature field determining the interaction method:
            - `Signature` - Primary electronic signature field
            - `Initials` - Participant's initials (for acknowledgments)
            - `Date` - Date/time selection
            - `FullName` - Participant's printed full name
            - `Checkbox` - Yes/no checkbox
            - `FreeText` - Custom text input with formatting
          example: Signature
        options:
          anyOf:
            - $ref: '#/components/schemas/Checkbox'
            - $ref: '#/components/schemas/Date'
            - $ref: '#/components/schemas/FreeText'
            - $ref: '#/components/schemas/FullName'
            - $ref: '#/components/schemas/Initials'
            - $ref: '#/components/schemas/Signature'
          type: object
          description: Type-specific configuration options. The schema variant must match the 'type' field.
        dependsOn:
          type: string
          format: uuid
          nullable: true
          description: |-
            Optional ID of another signature field on which the current field depends. 
            The dependency is reflected in the combined arrangement and filling of these fields.
          example: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
      example:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        participantId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        type: Signature
        placement:
          page: 1
          positionX: 100
          positionY: 200
          sizeX: 200
          sizeY: 50
        options:
          isRequired: true
          forType: Signature
        dependsOn: null
    SigningOrderSettings:
      type: object
      description: |-
        Controls the order in which participants receive and can complete their signing tasks.

        Signing order affects workflow and ensures documents are signed in the correct sequence
        (e.g., employee signs first, then manager, then HR).
      properties:
        type:
          type: string
          enum:
            - OneByOne
            - AllAtOnce
          description: |-
            Signing order strategy:
            - `OneByOne` - Sequential signing. Each participant receives the document only after 
              the previous participant completes their signature. Order is defined by participantsOrder array.
            - `AllAtOnce` - Parallel signing. All participants receive the document simultaneously 
              and can sign in any order.
          default: AllAtOnce
          example: OneByOne
        participantsOrder:
          type: array
          items:
            type: string
            format: uuid
          nullable: true
          description: |-
            Ordered array of participant IDs defining the signing sequence.
            Required when type is 'OneByOne', ignored when type is 'AllAtOnce'.

            The first participant in the array receives the document first, the second receives 
            it after the first completes signing, and so on.
          example:
            - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
            - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
            - 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
      x-examples:
        sequential:
          summary: Sequential signing workflow
          value:
            type: OneByOne
            participantsOrder:
              - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
              - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        parallel:
          summary: All participants sign simultaneously
          value:
            type: AllAtOnce
            participantsOrder: null
    SigningSessionDraft:
      type: object
      description: |-
        Complete configuration of a signing session draft containing all documents, participants,
        signature fields, and session settings.

        A draft is the preparation stage before sending documents to participants. It allows
        configuring all aspects of the signing workflow before initiating the signing process.

        Once configured and validated, the draft is converted to an active signing session.
      properties:
        signingSessionId:
          type: string
          format: uuid
          description: Unique identifier of the signing session draft
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        organizationId:
          type: string
          format: uuid
          description: Organization to which this signing session belongs
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        settingsSetId:
          type: string
          format: uuid
          description: Reference to the settings template applied to this session (branding, policies, etc.)
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        initiatorUserId:
          type: string
          format: uuid
          description: ID of the user who created this draft
          example: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        timestampFormat:
          type: string
          enum:
            - Usa
            - Spanish
          description: Format for displaying dates and times in the session
          default: Usa
          example: Usa
        isBulkSession:
          type: boolean
          description: |-
            Whether this is a bulk signing session where multiple participants sign identical documents.
            When true, use bulkParticipants array; when false, use participants array.
          example: false
        isLocked:
          type: boolean
          description: Whether the draft is locked from modifications.
          example: false
        isVoidDisabled:
          type: boolean
          description: Whether the void operation is disabled for this session (organization policy setting)
          example: false
        isSessionCopyDisabled:
          type: boolean
          description: Whether creating copies/duplicates of this session is disabled (organization policy setting)
          example: false
        isValidBulkParticipant:
          type: boolean
          nullable: true
          description: |-
            Validation status for bulk participants (only relevant when isBulkSession = true).
            Null if not a bulk session or not yet validated.
          example: true
        subject:
          type: string
          nullable: true
          description: Subject/title of the signing session shown to participants in notifications and UI
          maxLength: 500
          example: Annual Performance Review 2024
        documents:
          type: array
          items:
            $ref: '#/components/schemas/SigningConfigurationDocument'
          nullable: true
          description: Primary documents that participants will sign
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/SigningConfigurationAttachment'
          nullable: true
          description: Reference/supporting documents that participants can view but not sign
        participants:
          type: array
          items:
            $ref: '#/components/schemas/SigningConfigurationParticipant'
          nullable: true
          description: Participants for regular signing sessions (ignored if isBulkSession = true)
        bulkParticipants:
          type: array
          items:
            $ref: '#/components/schemas/BulkParticipant'
          nullable: true
          description: Participants for bulk signing sessions (only used if isBulkSession = true)
        signatureFields:
          type: array
          items:
            $ref: '#/components/schemas/SignatureField'
          nullable: true
          description: Interactive fields where participants provide signatures, dates, initials, etc.
        pageLabels:
          type: array
          items:
            $ref: '#/components/schemas/PageLabel'
          nullable: true
          description: Auto-generated labels showing metadata like session IDs or timestamps on signed documents
        reminderFrequency:
          type: string
          enum:
            - Never
            - Daily
            - Weekly
          nullable: true
          description: |-
            How often to send reminder notifications to participants who haven't signed:
            - `Never` - No automatic reminders
            - `Daily` - Send daily reminders until signed
            - `Weekly` - Send weekly reminders until signed
          example: Daily
        signingOrderSettings:
          allOf:
            - $ref: '#/components/schemas/SigningOrderSettings'
          type: object
          description: Configuration for the order in which participants receive and complete signing
      example:
        signingSessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        organizationId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        settingsSetId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        initiatorUserId: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        timestampFormat: Usa
        isBulkSession: false
        isLocked: false
        isVoidDisabled: false
        isSessionCopyDisabled: false
        isValidBulkParticipant: null
        subject: Employment Agreement - John Smith
        documents:
          - id: 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
            title: Employment Contract
            blobId: 3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f
            status: ProcessingReady
            pages: []
        attachments: []
        participants:
          - id: 4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a
            firstName: John
            lastName: Smith
            email: john.smith@example.com
            role: Signer
            language: English
        bulkParticipants: null
        signatureFields: []
        pageLabels: []
        reminderFrequency: Daily
        signingOrderSettings:
          type: AllAtOnce
          participantsOrder: null
    DocumentPage:
      type: object
      description: |-
        Represents a single rendered page from a document PDF in a draft configuration.
        Each page is stored as an image blob with physical dimensions for accurate field placement.

        Dimensions use the PDF standard: 1 point = 1/72 inch
        Common page sizes:
        - US Letter: 612 x 792 points
        - A4: 595 x 842 points
        - Legal: 612 x 1008 points
      properties:
        blobId:
          type: string
          format: uuid
          description: Reference to the blob containing the rendered page image (typically SVG or PNG)
          example: a1b2c3d4-5678-90ab-cdef-1234567890ab
        number:
          type: integer
          format: int32
          description: Sequential page number within the document (1-based index)
          minimum: 1
          example: 1
        width:
          type: number
          format: double
          description: |-
            Page width in points (72 points = 1 inch).
            Used for calculating signature field placement and ensuring fields fit within page boundaries.
          minimum: 0
          example: 595
        height:
          type: number
          format: double
          description: |-
            Page height in points (72 points = 1 inch).
            Used for calculating signature field placement and ensuring fields fit within page boundaries.
          minimum: 0
          example: 842
      x-examples:
        a4Page:
          summary: Standard A4 page
          value:
            blobId: a1b2c3d4-5678-90ab-cdef-1234567890ab
            number: 1
            width: 595
            height: 842
        letterPage:
          summary: US Letter page
          value:
            blobId: b2c3d4e5-6789-01bc-def0-2345678901bc
            number: 1
            width: 612
            height: 792
    PageLabelOptions:
      type: object
      description: |-
        Formatting options for page labels that appear on signed documents.
        Controls the visual appearance and layout of automatically generated labels.
      properties:
        fontSize:
          type: integer
          format: int32
          description: Font size in points for the label text
          minimum: 6
          maximum: 72
          default: 10
          example: 10
        fontWeight:
          type: string
          enum:
            - Normal
            - Bold
          description: |-
            Font weight (thickness) for the label text:
            - `Normal` - Regular weight text
            - `Bold` - Bold/heavy weight text for emphasis
          default: Normal
          example: Normal
        paddingX:
          type: number
          format: double
          description: Horizontal padding (in points) inside the label rectangle on left and right sides
          minimum: 0
          default: 5
          example: 5
        paddingY:
          type: number
          format: double
          description: Vertical padding (in points) inside the label rectangle on top and bottom sides
          minimum: 0
          default: 2
          example: 2
      example:
        fontSize: 10
        fontWeight: Normal
        paddingX: 5
        paddingY: 2
    RectPlacement:
      type: object
      description: |-
        Defines the rectangular placement area for elements (signature fields, labels) on a document page.

        **Coordinate System:**
        - Origin (0, 0) is at the **bottom-left** corner of the page
        - X-axis increases horizontally to the right
        - Y-axis increases vertically upward
        - All measurements are in **points** (1 point = 1/72 inch)

        **Important:** This differs from typical screen coordinates where (0,0) is top-left.

        Example calculation for A4 page (595 x 842 points):
        - Top-left corner: positionX=0, positionY=792 (842 - 50 height)
        - Bottom-right corner: positionX=395 (595 - 200 width), positionY=0
      properties:
        page:
          type: integer
          format: int32
          description: Page number where the element is placed (1-based index, first page is 1)
          minimum: 1
          example: 1
        positionX:
          type: number
          format: double
          description: |-
            Horizontal position of the element's **bottom-left** corner in points.
            Distance from the left edge of the page.
          minimum: 0
          example: 100
        positionY:
          type: number
          format: double
          description: |-
            Vertical position of the element's **bottom-left** corner in points.
            Distance from the bottom edge of the page (NOT from top).
          minimum: 0
          example: 700
        sizeX:
          type: number
          format: double
          description: Width of the rectangular area in points
          minimum: 0.1
          example: 200
        sizeY:
          type: number
          format: double
          description: Height of the rectangular area in points
          minimum: 0.1
          example: 50
      x-examples:
        topRightCorner:
          summary: Field in top-right corner of A4 page
          value:
            page: 1
            positionX: 395
            positionY: 792
            sizeX: 200
            sizeY: 50
        bottomLeftCorner:
          summary: Field in bottom-left corner
          value:
            page: 1
            positionX: 0
            positionY: 0
            sizeX: 200
            sizeY: 50
        centered:
          summary: Field centered on A4 page
          value:
            page: 1
            positionX: 197.5
            positionY: 396
            sizeX: 200
            sizeY: 50
    SignatureFieldDeclaration:
      type: object
      description: |-
        Declaration of a new signature field to be added to a signing session draft.
        Unlike SignatureFieldDefinition, this does not include IDs as they are assigned by the server.

        Used in API requests when adding fields to a draft session. The server will generate
        unique IDs and link the field to the specified document and participant.
      properties:
        type:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          description: |-
            Type of signature field to create:
            - `Signature` - Electronic signature field (primary signing mechanism)
            - `Initials` - Initials field for acknowledgments
            - `Date` - Date/time selection field
            - `FullName` - Participant's full name field
            - `Checkbox` - Yes/no checkbox field
            - `FreeText` - Custom text input field
          example: Signature
        placement:
          allOf:
            - $ref: '#/components/schemas/RectPlacement'
          type: object
          description: Position and size of the field on the document page
        options:
          anyOf:
            - $ref: '#/components/schemas/Checkbox'
            - $ref: '#/components/schemas/Date'
            - $ref: '#/components/schemas/FreeText'
            - $ref: '#/components/schemas/FullName'
            - $ref: '#/components/schemas/Initials'
            - $ref: '#/components/schemas/Signature'
          type: object
          description: |-
            Field-specific configuration options. The schema type must match the 'type' property.
            For example, if type is "Signature", use Signature options.
      example:
        type: Signature
        placement:
          page: 1
          positionX: 100
          positionY: 200
          sizeX: 200
          sizeY: 50
        options:
          isRequired: true
          forType: Signature
    SignatureFieldOptions:
      type: object
      description: |-
        Base configuration options for signature fields in a draft session.
        Each field type extends this with specific formatting and behavior options.
        Use the 'forType' discriminator to determine which subtype applies.
      properties:
        isRequired:
          type: boolean
          description: |-
            Whether the participant must fill this field to complete signing.
            Required fields prevent session completion until filled.
          default: false
          example: true
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: |-
            Discriminator property indicating the specific field type and options schema:
            - `Signature` - Electronic signature with drawing/typing/upload options
            - `Initials` - Shortened signature for acknowledgments
            - `Date` - Date/time picker with format options
            - `FullName` - Auto-filled participant name
            - `Checkbox` - Simple yes/no toggle
            - `FreeText` - Custom text input with formatting
          example: Signature
    Checkbox:
      type: object
      description: |-
        Configuration options for checkbox signature fields.
        Checkboxes are binary fields where participants check/uncheck a box,
        commonly used for consent, acknowledgments, or yes/no questions.
      allOf:
        - $ref: '#/components/schemas/SignatureFieldOptions'
      properties:
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: Type discriminator, always set to "Checkbox"
          example: Checkbox
      example:
        isRequired: true
        forType: Checkbox
    Date:
      type: object
      description: |-
        Configuration options for date/time signature fields.
        Participants select a date, time, or both using a date picker interface.
        Useful for recording when actions are taken or scheduling events.
      allOf:
        - $ref: '#/components/schemas/SignatureFieldOptions'
      properties:
        displayMode:
          type: string
          enum:
            - Date
            - DateTime
            - Time
          description: |-
            Format for date/time input and display:
            - `Date` - Date only (e.g., "12/17/2024")
            - `DateTime` - Date and time combined (e.g., "12/17/2024 2:30 PM")
            - `Time` - Time only (e.g., "2:30 PM")
          default: Date
          example: DateTime
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: Type discriminator, always set to "Date"
          example: Date
      example:
        isRequired: false
        displayMode: DateTime
        forType: Date
    FreeText:
      type: object
      description: |-
        Configuration options for free text signature fields.
        Participants enter custom text with configurable formatting.
        Ideal for job titles, addresses, custom notes, or any text input.
      allOf:
        - $ref: '#/components/schemas/SignatureFieldOptions'
      properties:
        alignMode:
          type: string
          enum:
            - Justify
            - Left
          description: |-
            Text alignment within the field boundary:
            - `Justify` - Text spreads across full width of the field
            - `Left` - Text aligns to the left edge with natural spacing
          default: Justify
          example: Left
        fontSize:
          type: integer
          format: int32
          description: Font size in points for the entered text
          minimum: 6
          maximum: 72
          default: 10
          example: 12
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: Type discriminator, always set to "FreeText"
          example: FreeText
      example:
        isRequired: true
        alignMode: Left
        fontSize: 12
        forType: FreeText
    FullName:
      type: object
      description: |-
        Configuration options for full name signature fields.
        Automatically populated with the participant's full legal name from their profile.
        Used for printed name fields commonly required alongside signatures.
      allOf:
        - $ref: '#/components/schemas/SignatureFieldOptions'
      properties:
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: Type discriminator, always set to "FullName"
          example: FullName
      example:
        isRequired: true
        forType: FullName
    Initials:
      type: object
      description: |-
        Configuration options for initials signature fields.
        Participants provide their initials using electronic input (typed, drawn, or uploaded).
        Commonly used for acknowledging individual pages, clauses, or changes in multi-page documents.
      allOf:
        - $ref: '#/components/schemas/SignatureFieldOptions'
      properties:
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: Type discriminator, always set to "Initials"
          example: Initials
      example:
        isRequired: true
        forType: Initials
    Signature:
      type: object
      description: |-
        Configuration options for electronic signature fields.
        The primary field type where participants provide their legally binding signature.
        Participants can draw, type, or upload their signature image.
      allOf:
        - $ref: '#/components/schemas/SignatureFieldOptions'
      properties:
        forType:
          type: string
          enum:
            - Initials
            - Signature
            - Date
            - Checkbox
            - FreeText
            - FullName
          readOnly: true
          description: Type discriminator, always set to "Signature"
          example: Signature
      example:
        isRequired: true
        forType: Signature
    AddSigner:
      type: object
      description: |-
        Request to add a new signer participant to a signing session draft.
        The signer will receive a signing invitation via the specified delivery methods
        and will be able to sign the documents.

        At least one delivery method (Email or Sms) with corresponding contact information must be provided.
      properties:
        firstName:
          type: string
          nullable: true
          description: Participant's first (given) name
          minLength: 1
          maxLength: 100
          example: John
        middleName:
          type: string
          nullable: true
          description: Participant's middle name or initial (optional)
          maxLength: 100
          example: Robert
        lastName:
          type: string
          nullable: true
          description: Participant's last (family) name
          minLength: 1
          maxLength: 100
          example: Smith
        email:
          type: string
          nullable: true
          description: |-
            Email address for sending signing invitations.
            Required if Email is included in deliveryMethods.
          format: email
          maxLength: 256
          example: john.smith@example.com
        phone:
          type: string
          nullable: true
          description: |-
            Phone number for sending SMS notifications.
            Required if Sms is included in deliveryMethods.
            Must be a 10-digit phone number.
          pattern: ^\d{10}$
          example: '2025551234'
        deliveryMethods:
          type: array
          items:
            type: string
            enum:
              - Email
              - Sms
          nullable: true
          description: |-
            Methods for delivering the signing link to the participant:
            - `Email` - Send invitation via email (requires email address)
            - `Sms` - Send invitation via SMS (requires phone number)

            Multiple methods can be specified for better delivery reliability.
          minItems: 1
          example:
            - Email
        language:
          type: string
          enum:
            - English
            - Spanish
          description: |-
            Preferred language for the participant's signing interface and notifications:
            - `English` - English UI and emails
            - `Spanish` - Spanish UI and emails
          default: English
          example: English
      x-examples:
        emailParticipant:
          summary: Add participant with email delivery
          value:
            firstName: John
            middleName: Robert
            lastName: Smith
            email: john.smith@example.com
            phone: null
            deliveryMethods:
              - Email
            language: English
        smsParticipant:
          summary: Add participant with SMS delivery
          value:
            firstName: Maria
            middleName: null
            lastName: Garcia
            email: null
            phone: '2025551234'
            deliveryMethods:
              - Sms
            language: Spanish
        bothMethods:
          summary: Add participant with both email and SMS
          value:
            firstName: Jane
            middleName: null
            lastName: Doe
            email: jane.doe@example.com
            phone: '2025551234'
            deliveryMethods:
              - Email
              - Sms
            language: English
    UpdateParticipant:
      type: object
      description: |-
        Request to update an existing participant's information in a signing session draft.

        Important restrictions:
        - Can only update participants in draft sessions (not started sessions)
        - All fields are required (partial updates are not supported)
      properties:
        firstName:
          type: string
          nullable: true
          description: Updated first (given) name of the participant
          minLength: 1
          maxLength: 100
          example: John
        middleName:
          type: string
          nullable: true
          description: Updated middle name or initial (optional)
          maxLength: 100
          example: Robert
        lastName:
          type: string
          nullable: true
          description: Updated last (family) name of the participant
          minLength: 1
          maxLength: 100
          example: Smith
        email:
          type: string
          nullable: true
          description: |-
            Updated email address for the participant.
            Required if Email is in deliveryMethods.
          format: email
          maxLength: 256
          example: john.smith@newcompany.com
        phone:
          type: string
          nullable: true
          description: |-
            Updated phone number for the participant.
            Required if Sms is in deliveryMethods.
            Must be a 10-digit phone number.
          pattern: ^\d{10}$
          example: '2025551234'
        deliveryMethods:
          type: array
          items:
            type: string
            enum:
              - Email
              - Sms
          nullable: true
          description: |-
            Updated delivery methods for sending signing invitations.
            Changing this will trigger a new invitation to be sent.
          minItems: 1
          example:
            - Email
            - Sms
        language:
          type: string
          enum:
            - English
            - Spanish
          description: Updated language preference for UI and notifications
          default: English
          example: English
      x-examples:
        updateEmail:
          summary: Update participant's email address
          value:
            firstName: John
            middleName: Robert
            lastName: Smith
            email: john.smith@newcompany.com
            phone: null
            deliveryMethods:
              - Email
            language: English
        updatePhone:
          summary: Update participant's phone number
          value:
            firstName: Maria
            middleName: null
            lastName: Garcia
            email: null
            phone: '2025551234'
            deliveryMethods:
              - Sms
            language: Spanish
        updateLanguage:
          summary: Change participant's language preference
          value:
            firstName: Jane
            middleName: null
            lastName: Doe
            email: jane.doe@example.com
            phone: null
            deliveryMethods:
              - Email
            language: Spanish
    SetOneByOneSigningOrder:
      type: object
      description: |-
        Request to configure sequential (one-by-one) signing order for a draft session.

        In sequential signing:
        - First participant receives invitation immediately
        - Second participant receives invitation after first completes signing
        - And so on...

        This ensures documents are signed in a specific order, useful for approval chains
        (e.g., employee → manager → HR → legal).
      properties:
        participantsOrder:
          type: array
          items:
            type: string
            format: uuid
          nullable: true
          description: |-
            Ordered array of participant IDs defining the signing sequence.

            The participant at index 0 signs first, index 1 signs second, etc.
            All participants in the session must be included in this array.

            Example workflow with 3 participants:
            1. Participant A receives invitation immediately
            2. After A signs, Participant B receives invitation
            3. After B signs, Participant C receives invitation
            4. After C signs, session is complete
          minItems: 1
          example:
            - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
            - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
            - 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
      x-examples:
        twoParticipants:
          summary: Simple sequential signing with 2 participants
          value:
            participantsOrder:
              - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
              - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        approvalChain:
          summary: Approval chain with 4 levels
          value:
            participantsOrder:
              - 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
              - 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
              - 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
              - 3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f
    SetSigningSessionParameters:
      type: object
      description: |-
        Request to update basic parameters of a signing session draft including subject and reminder settings.
        These parameters affect how the session is presented to participants and when reminders are sent.
      properties:
        subject:
          type: string
          nullable: true
          description: |-
            Updated subject/title of the signing session.
            This appears in email notifications and the signing interface header.
          maxLength: 500
          example: Updated Employment Agreement - December 2024
        reminderFrequency:
          type: string
          enum:
            - Never
            - Daily
            - Weekly
          nullable: true
          description: |-
            Frequency for sending automatic reminder notifications to participants who haven't signed:
            - `Never` - No automatic reminders will be sent
            - `Daily` - Send a reminder every day until the participant signs
            - `Weekly` - Send a reminder once per week until the participant signs

            Reminders are only sent during active signing sessions, not for drafts.
          example: Daily
      x-examples:
        withDailyReminders:
          summary: Set daily reminders
          value:
            subject: Urgent - Contract Signing Required
            reminderFrequency: Daily
        noReminders:
          summary: Disable reminders
          value:
            subject: Internal Agreement - No Rush
            reminderFrequency: Never
        weeklyReminders:
          summary: Set weekly reminders
          value:
            subject: Annual Review Document
            reminderFrequency: Weekly
    AddSignatureField:
      type: object
      description: |-
        Request to add a single signature field to a document in a draft signing session.

        The field will be created at the specified position and assigned to a participant.
        After adding fields, the draft can be validated and started to send to participants.
      properties:
        participantId:
          type: string
          format: uuid
          nullable: true
          description: ID of the participant who will fill this field.
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        documentId:
          type: string
          format: uuid
          description: ID of the document where the signature field will be placed
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        field:
          allOf:
            - $ref: '#/components/schemas/SignatureFieldDeclaration'
          type: object
          description: |-
            Declaration of the signature field to create, including type, position, and options.
            The server will assign a unique ID to the created field.
      example:
        participantId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        field:
          type: Signature
          placement:
            page: 1
            positionX: 100
            positionY: 200
            sizeX: 200
            sizeY: 50
          options:
            isRequired: true
            forType: Signature
    AllInOneDocument:
      type: object
      description: |-
        Represents the combined all-in-one document that merges all signed documents from 
        all participants into a single PDF file for convenient download and archival.

        This document is generated after the signing session is completed and contains:
        - All original documents with signatures
        - Audit trail information
        - Participant details
        - Signing timestamps
      properties:
        title:
          type: string
          nullable: true
          description: Title of the combined document, typically includes the session subject
          example: Employment Agreement - All Signatures Combined.pdf
        status:
          type: string
          enum:
            - InProgress
            - Ready
            - Failed
          description: |-
            Processing status of the all-in-one document:
            - `InProgress` - Document is being generated from individual signed documents
            - `Ready` - Document is ready to download
            - `Failed` - Generation failed, may need to retry
          example: Ready
      example:
        title: Employment Agreement - All Signatures.pdf
        status: Ready
    SigningViewAttachment:
      type: object
      description: |-
        Brief information about an attachment document in a signing session.
        Attachments are reference materials participants can view but do not sign.
      properties:
        attachmentId:
          type: string
          format: uuid
          description: Unique identifier of the attachment document
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title:
          type: string
          nullable: true
          description: Display name of the attachment document
          example: Company Policy Handbook.pdf
      example:
        attachmentId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title: Employee Handbook - 2024.pdf
    SigningViewDocument:
      type: object
      description: |-
        Brief information about a document for signing in a signing session.
        Documents for signing are the documents that contain signature fields and must be signed.
      properties:
        documentId:
          type: string
          format: uuid
          description: Unique identifier of the document
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        title:
          type: string
          nullable: true
          description: Display name of the document shown to participants
          example: Employment Agreement.pdf
      example:
        documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        title: Employment Agreement.pdf
    SigningViewParticipant:
      type: object
      description: |-
        Complete information about a participant in an active or completed signing session,
        including their personal details, contact information, signing status, and notification history.
      properties:
        participantId:
          type: string
          format: uuid
          description: Unique identifier of the participant in this signing session
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        order:
          type: integer
          format: int32
          nullable: true
          description: |-
            Position in the signing order for sequential (one-by-one) sessions.
            Null for parallel (all-at-once) sessions where order doesn't matter.
            1 = signs first, 2 = signs second, etc.
          minimum: 1
          example: 1
        firstName:
          type: string
          nullable: true
          description: Participant's first name
          example: John
        middleName:
          type: string
          nullable: true
          description: Participant's middle name or initial
          example: Robert
        lastName:
          type: string
          nullable: true
          description: Participant's last name
          example: Smith
        email:
          type: string
          nullable: true
          description: Email address where notifications are sent
          example: john.smith@example.com
        phone:
          type: string
          nullable: true
          description: Phone number for SMS notifications (10 digits)
          pattern: ^\d{10}$
          example: '2025551234'
        role:
          type: string
          enum:
            - Initiator
            - Signer
          description: |-
            Participant's role in the session:
            - `Initiator` - Created the signing session
            - `Signer` - Signs the documents
          example: Signer
        deliveryMethods:
          type: array
          items:
            type: string
            enum:
              - Email
              - Sms
          nullable: true
          description: Methods used for delivering signing invitations to this participant
          example:
            - Email
        status:
          type: string
          enum:
            - Pending
            - InProgress
            - Signed
            - Declined
            - Voided
            - Expired
          description: |-
            Current status of the participant's signing process:
            - `Pending` - Invitation not yet sent or not opened
            - `InProgress` - Participant opened the signing link and is reviewing/signing
            - `Signed` - Participant completed all required signatures
            - `Declined` - Participant declined to sign
            - `Voided` - Session was cancelled/voided
            - `Expired` - Signing link expired before completion
          example: Signed
        signedAt:
          type: string
          format: date-time
          nullable: true
          description: |-
            Timestamp when the participant completed signing (UTC).
            Null if the participant hasn't signed yet.
          example: '2024-12-17T14:30:00Z'
        isCurrentUser:
          type: boolean
          description: Whether this participant is the currently authenticated user making the API request
          example: false
        notificationErrors:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantNotificationError'
          nullable: true
          description: |-
            List of errors that occurred when trying to send notifications to this participant.
            Empty array or null indicates successful delivery.
      example:
        participantId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
        order: 1
        firstName: John
        middleName: Robert
        lastName: Smith
        email: john.smith@example.com
        phone: '2025551234'
        role: Signer
        deliveryMethods:
          - Email
        status: Signed
        signedAt: '2024-12-17T14:30:00Z'
        isCurrentUser: false
        notificationErrors: []
    ParticipantNotificationError:
      type: object
      description: |-
        Represents an error that occurred while attempting to send a notification to a participant.
        Notification errors indicate delivery failures and help diagnose communication issues.
      properties:
        deliveryMethod:
          type: string
          enum:
            - Email
            - Sms
          description: |-
            The delivery method that failed:
            - `Email` - Email delivery failed
            - `Sms` - SMS delivery failed
          example: Email
        notificationErrorType:
          type: string
          enum:
            - UndefinedError
            - AuthenticationError
            - ConnectionError
            - EmailMessageRejected
            - InvalidToNumber
            - InvalidFromNumber
          description: |-
            Specific type of error that occurred:
            - `UndefinedError` - Unknown error occurred
            - `AuthenticationError` - Failed to authenticate with email/SMS provider
            - `ConnectionError` - Network connection issue with notification service
            - `EmailMessageRejected` - Email was rejected by recipient's server (invalid address, spam filter)
            - `InvalidToNumber` - Phone number format is invalid or not recognized
            - `InvalidFromNumber` - Sender phone number is invalid or not authorized
          example: EmailMessageRejected
      x-examples:
        emailRejected:
          summary: Email rejected by recipient server
          value:
            deliveryMethod: Email
            notificationErrorType: EmailMessageRejected
        invalidPhone:
          summary: Invalid phone number format
          value:
            deliveryMethod: Sms
            notificationErrorType: InvalidToNumber
        connectionError:
          summary: Network connection failure
          value:
            deliveryMethod: Email
            notificationErrorType: ConnectionError
    SignedDocument:
      type: object
      description: |-
        Represents a signed document after a participant has completed signing.
        Each participant gets their own signed copy with their signatures applied.

        Signed documents include:
        - Original document pages
        - All signature fields filled by the participant
        - Audit trail certificate (who signed, when, IP address)
      properties:
        signedDocumentId:
          type: string
          format: uuid
          description: Unique identifier of the signed document copy
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title:
          type: string
          nullable: true
          description: Title of the signed document, typically includes participant name
          example: Employment Agreement - John Smith (Signed).pdf
        processingStatus:
          type: string
          enum:
            - InProgress
            - Ready
            - Failed
          description: |-
            Status of signed document generation:
            - `InProgress` - Document is being generated with signatures applied
            - `Ready` - Document is ready to download
            - `Failed` - Generation failed, may require retry
          example: Ready
      example:
        signedDocumentId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        title: Employment Agreement - John Smith (Signed).pdf
        processingStatus: Ready
    SigningSession:
      type: object
      description: |-
        Complete view of an active or completed signing session with all related information
        including documents, participants, signatures, and attachments.

        This is the primary model returned when retrieving signing session details.
        It provides a comprehensive snapshot of the session state.
      properties:
        signingSessionId:
          type: string
          format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        bulkSessionId:
          type: string
          format: uuid
          nullable: true
          description: |-
            ID of the parent bulk session if this is a child session in a bulk signing workflow.
            Null for regular (non-bulk) signing sessions.
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        subject:
          type: string
          nullable: true
          description: Subject/title of the signing session
          example: Employment Agreement - John Smith
        canBeVoided:
          type: boolean
          description: Whether the current user has permission to void (cancel) this session
          example: true
        canBeCopied:
          type: boolean
          description: Whether the current user has permission to duplicate/copy this session
          example: true
        status:
          type: string
          enum:
            - Draft
            - ReadyToStart
            - Pending
            - InProgress
            - Finished
            - Declined
            - Voided
            - Expired
          description: |-
            Current status of the signing session lifecycle:
            - `Draft` - Being configured, not yet sent to participants
            - `ReadyToStart` - Configured and ready to send
            - `Pending` - Sent but no participant has opened it yet
            - `InProgress` - At least one participant is actively signing
            - `Finished` - All participants have completed signing
            - `Declined` - A participant declined to sign
            - `Voided` - Session was cancelled/annulled
            - `Expired` - Session expired before all signatures collected
          example: InProgress
        documents:
          type: array
          items:
            $ref: '#/components/schemas/SigningViewDocument'
          nullable: true
          description: Primary documents that participants sign
        participants:
          type: array
          items:
            $ref: '#/components/schemas/SigningViewParticipant'
          nullable: true
          description: All participants in the session with their current signing status
        signedDocuments:
          type: array
          items:
            $ref: '#/components/schemas/SignedDocument'
          nullable: true
          description: |-
            Individual signed document copies generated for each participant after they complete signing.
            Each participant gets their own copy with their signatures applied.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/SigningViewAttachment'
          nullable: true
          description: Reference/supporting documents attached to the session
        allInOneDocument:
          allOf:
            - $ref: '#/components/schemas/AllInOneDocument'
          type: object
          description: |-
            Combined document merging all participants' signatures into one file.
            Only available after the session is finished.
      example:
        signingSessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        bulkSessionId: null
        subject: Employment Agreement - December 2024
        canBeVoided: true
        canBeCopied: true
        status: Finished
        documents:
          - documentId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
            title: Employment Contract.pdf
        participants:
          - participantId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
            firstName: John
            lastName: Smith
            email: john.smith@example.com
            role: Signer
            status: Signed
            signedAt: '2024-12-17T14:30:00Z'
        signedDocuments:
          - signedDocumentId: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
            title: Employment Contract - John Smith (Signed).pdf
            processingStatus: Ready
        attachments: []
        allInOneDocument:
          title: Employment Agreement - All Signatures.pdf
          status: Ready
    GetSigningSessionsSummaryResult:
      type: object
      description: |-
        Summary statistics about signing sessions grouped by status.
        Provides quick counts for dashboard widgets and overview screens.

        Useful for showing users how many sessions need attention, are in progress, etc.
      properties:
        sessionsToSignCount:
          type: integer
          format: int32
          description: |-
            Number of sessions where the current user is a participant and needs to sign.
            Includes sessions in any status where user action is pending.
          minimum: 0
          example: 5
        draftsCount:
          type: integer
          format: int32
          description: |-
            Number of sessions in Draft status (being configured, not yet sent).
            Only includes drafts created by or visible to the current user.
          minimum: 0
          example: 3
        readyToStartCount:
          type: integer
          format: int32
          description: |-
            Number of sessions in ReadyToStart status (configured and ready to send to participants).
            Requires manual action to initiate sending.
          minimum: 0
          example: 2
        inProgressCount:
          type: integer
          format: int32
          description: |-
            Number of sessions in InProgress status (sent to participants, awaiting signatures).
            Includes sessions where at least one participant has started but not all have finished.
          minimum: 0
          example: 12
        needsActionCount:
          type: integer
          format: int32
          description: |-
            Number of sessions requiring immediate user attention.
            May include sessions with errors, declined sessions, or sessions awaiting approval.
          minimum: 0
          example: 1
      example:
        sessionsToSignCount: 5
        draftsCount: 3
        readyToStartCount: 2
        inProgressCount: 12
        needsActionCount: 1
    SearchSigningSessionsResult:
      type: object
      description: |-
        Paginated search results for signing sessions with metadata about total count and pagination.

        Returned by the search/filter endpoint when querying signing sessions with filters,
        sorting, and pagination parameters.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SigningSessionItem'
          nullable: true
          description: |-
            Array of signing session items matching the search criteria.
            Empty array if no sessions match the filters.
        totalItemsCount:
          type: integer
          format: int32
          description: Total number of sessions matching the search criteria across all pages
          minimum: 0
          example: 47
        pagesCount:
          type: integer
          format: int32
          description: Total number of pages available based on pageSize and totalItemsCount
          minimum: 0
          example: 3
        pageIndex:
          type: integer
          format: int32
          description: Current page index (0-based, matches the request parameter)
          minimum: 0
          example: 0
        pageSize:
          type: integer
          format: int32
          description: Number of items per page (matches the request parameter)
          minimum: 1
          example: 20
      example:
        items:
          - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            isBulk: false
            subject: Employment Agreement
            created: '2024-12-17T10:00:00Z'
            status: InProgress
            currentUserNeedToSign: false
            hasNotificationErrors: false
            canBeDeleted: true
          - id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
            isBulk: false
            subject: NDA Agreement
            created: '2024-12-16T15:30:00Z'
            status: Finished
            currentUserNeedToSign: false
            hasNotificationErrors: false
            canBeDeleted: true
        totalItemsCount: 47
        pagesCount: 3
        pageIndex: 0
        pageSize: 20
    SigningSessionItem:
      type: object
      description: |-
        Brief summary of a signing session for list views and search results.
        Contains essential information without the full details of documents and participants.

        Use this model for displaying lists of sessions where full details aren't needed.
        For complete session information, fetch the individual session by ID.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the signing session
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        isBulk:
          type: boolean
          description: |-
            Whether this is a bulk signing session (multiple participants signing identical documents)
            or a regular session (specific participants signing specific documents).
          example: false
        subject:
          type: string
          nullable: true
          description: Session subject/title
          example: Annual Review Agreement 2024
        created:
          type: string
          format: date-time
          description: UTC timestamp when the session was created
          example: '2024-12-17T10:00:00Z'
        status:
          type: string
          enum:
            - Draft
            - ReadyToStart
            - Pending
            - InProgress
            - Finished
            - Declined
            - Voided
            - Expired
          description: |-
            Current lifecycle status of the session:
            - `Draft` - Configuration in progress
            - `ReadyToStart` - Ready to send to participants
            - `Pending` - Sent, awaiting first participant action
            - `InProgress` - One or more participants actively signing
            - `Finished` - All signatures collected
            - `Declined` - Rejected by a participant
            - `Voided` - Cancelled by initiator
            - `Expired` - Deadline passed without completion
          example: InProgress
        currentUserNeedToSign:
          type: boolean
          description: Whether the authenticated user is a participant who needs to sign this session
          example: true
        hasNotificationErrors:
          type: boolean
          description: |-
            Whether any notification delivery errors occurred for this session.
            True indicates some participants may not have received invitations.
          example: false
        canBeDeleted:
          type: boolean
          description: Whether the current user has permission to delete this session
          example: true
      example:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        isBulk: false
        subject: Employment Agreement - John Smith
        created: '2024-12-17T10:00:00Z'
        status: InProgress
        currentUserNeedToSign: false
        hasNotificationErrors: false
        canBeDeleted: true
    VoidSigningSession:
      type: object
      description: |-
        Request to void (cancel/annul) a signing session, preventing any further actions on it.
        Once voided, the session cannot be reactivated or signed.

        Use cases:
        - Document contains errors and needs to be replaced
        - Session was created by mistake
        - Legal requirements changed
        - Participant requested cancellation
      properties:
        reason:
          type: string
          nullable: true
          description: |-
            Reason for voiding the signing session. This will be visible to all participants
            and stored in the audit trail.
          minLength: 1
          maxLength: 1000
          example: Document contained incorrect salary information
      example:
        reason: Document needs to be revised due to updated terms
    UpdateParticipantDeliveryMethods:
      type: object
      description: |-
        Request to update the delivery methods and contact information for a participant in an active signing session.

        Restrictions:
        - Can only be updated for participants in Pending or Activated status
        - Cannot be changed after participant has used the signing link
        - New notification with updated link will be sent to the participant
      properties:
        deliveryMethods:
          type: array
          items:
            type: string
            enum:
              - Email
              - Sms
          nullable: true
          description: |-
            Methods to use for delivering the signing link to the participant.

            Available methods:
            - `Email` - Send link via email (requires valid email address)
            - `Sms` - Send link via SMS (requires valid phone number)

            Multiple methods can be specified for redundancy.
          example:
            - Email
            - Sms
        email:
          type: string
          nullable: true
          description: |-
            Email address for the participant. Required if Email is included in deliveryMethods.
            Must be a valid email format.
          format: email
          maxLength: 256
          example: john.doe@example.com
        phone:
          type: string
          nullable: true
          description: |-
            Phone number for the participant. Required if Sms is included in deliveryMethods.
            Must be a 10-digit phone number.
          pattern: ^\d{10}$
          example: '2025551234'
      x-examples:
        emailOnly:
          summary: Update to email delivery only
          value:
            deliveryMethods:
              - Email
            email: participant@example.com
            phone: null
        bothMethods:
          summary: Use both email and SMS
          value:
            deliveryMethods:
              - Email
              - Sms
            email: participant@example.com
            phone: '2025551234'
        smsOnly:
          summary: Update to SMS delivery only
          value:
            deliveryMethods:
              - Sms
            email: null
            phone: '2025551234'
    ErrorResponse:
      description: Standard error response
      type: object
      required:
        - error
        - message
      properties:
        error:
          description: Error code
          type: string
          example: VALIDATION_ERROR
        message:
          description: Human-readable error message
          type: string
          example: Invalid request parameters
        details:
          description: Additional error details
          type: array
          items:
            type: object
            properties:
              field:
                description: Field name that caused the error
                type: string
                example: email
              message:
                description: Field-specific error message
                type: string
                example: Email address is required
        correlationId:
          description: Request correlation ID for troubleshooting
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
  responses:
    '400':
      description: Bad Request - Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '401':
      description: Unauthorized - Invalid or missing authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '403':
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '404':
      description: Not Found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      $ref: '#/components/responses/400'
    Unauthorized:
      $ref: '#/components/responses/401'
    Forbidden:
      $ref: '#/components/responses/403'
    NotFound:
      $ref: '#/components/responses/404'
    InternalServerError:
      $ref: '#/components/responses/500'
