openapi: 3.1.0
info:
  title: Skribble API v2
  version: 2.2.0
  description: |-
    The Skribble API v2 documentation describes the publicly available Skribble
    API version 2. The API allows businesses and teams of any size to integrate
    the e-signing solution of Skribble with internal systems, software, or SaaS
    solutions. It provides a simple interface to create and manage signature
    requests programmatically. Signature requests define who signs what and
    describe the document flow between participants. Actual signing occurs in
    the Skribble web application.

    API v2 provides enhanced features including creating, finding, and
    triggering signature requests, user and monitoring details, and reporting
    activities. It maintains backward compatibility with API v1 but upgrading is
    recommended to access the latest features. Migration from API v1 involves
    updating base URLs, renaming fields, and adjusting visual signature
    positions.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://www.skribble.com/en-eu/terms-of-use/
  contact:
    name: Skribble Engineering
    url: https://skribble.com
    email: support@skribble.com
servers:
  - url: https://api.skribble.com/v2
    description: Production - Switzerland
  - url: https://api.skribble.de/v2
    description: Production - Germany
security: []
tags:
  - name: Access
    description: Endpoints for authentication, authorization, and user access management.
  - name: Document
    description: Endpoints for uploading and managing documents.
  - name: Signature
    description: Endpoints for creating and managing signature requests.
  - name: Signature Signer
    description: Endpoints for managing signers on a signature request.
  - name: Signature Attachment
    description: Endpoints for managing attachments on a signature request.
  - name: Signature Handling
    description: Endpoints for handling signature requests and callbacks.
  - name: Seal
    description: Endpoints for applying electronic seals to documents.
  - name: SendTo
    description: Endpoints for the Send-To signing flow.
  - name: User
    description: Endpoints for user information and signature quality queries.
  - name: Identification
    description: |-
      Endpoints for retrieving, checking status, and downloading identification evidence
      collected during identification.
  - name: Report
    description: Endpoints for signature activity reporting.
  - name: Monitoring
    description: Endpoints for monitoring system health.
paths:
  /access/login:
    post:
      tags:
        - Access
      summary: Authenticate and Obtain an Access Token
      description: |-
        To use the Skribble API, you first need an API key and an API user. Both
        can be managed on the API key page in your business profile. Consult our
        [guide](https://docs.skribble.com/business-admin/api/apicreate.html) for
        setup instructions.


        Skribble offers two types of API keys:


        **Demo API keys**

        Demo API keys are for testing and development purposes. Signatures created
        with demo keys have no legal weight and are free of charge.

        Demo keys can be identified by their name, which starts with **api_demo**.


        **Production API keys**

        Production API keys are used for live systems. Signatures created with
        production keys will be invoiced.

        Production keys can be identified by their name, which starts with
        **api_production** or, in some cases, **api_prod**.

        > **⚠ Note**
        > All costs incurred by signature requests created with your API keys will
        > be **charged to your business**. We recommend starting with a demo API
        > key during development and testing, and switching to a production key
        > only once testing is complete.

        For help setting up Skribble Business, contact us at
        [support@skribble.com](mailto:support@skribble.com).


        To obtain an access token, authenticate using the `/access/login` endpoint.
        You can pass your credentials as raw JSON or as `x-www-form-urlencoded`
        key-value pairs (see example requests).

        Upon successful authentication, a JSON Web Token (JWT) is returned. This
        JWT must be included in nearly every API request.

        The access token is passed in the `Authorization` HTTP header using the
        `Bearer` scheme. Example:
        `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI...`

        ### Token life cycle

        #### API key

        API keys have a long but finite lifetime. The validity period depends on
        the volume of API calls and is agreed upon individually as part of the
        shared secret agreement.

        #### Access token

        Access tokens have a lifetime of approximately **20 minutes**. Automatic
        token renewal is not currently supported.

        #### Logout

        There is **no logout endpoint**. Access tokens expire automatically after
        the defined lifetime.
      operationId: accessLogin
      security:
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              Credentials:
                $ref: '#/components/examples/Login'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              Credentials:
                $ref: '#/components/examples/Login'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                description: JSON Web Token (JWT)
              example: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJWlMxY0pXQXlXVFdZeDR6dXRGNzJlYWVILT...
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          description: |-
            Login failed — username or API key is invalid.

            The response body shape depends on the request `Content-Type`:

            - `application/json` request → `application/json` Problem envelope
            - `application/x-www-form-urlencoded` request → `text/plain` body containing the error message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
              example:
                type: https://api.skribble.com/problem/problem-with-message
                method: POST
                path: /v2/access/login
                status: 403
                message: Please ensure your username and api-key are correct
            text/plain:
              schema:
                type: string
              example: Please ensure your username and api-key are correct!
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests:
    post:
      tags:
        - Signature
      summary: Create a Signature Request
      description: |-
        Creates a new `SignatureRequest`, which is the primary object of the Skribble API.
        A `SignatureRequest` defines who signs what and under which conditions. It specifies
        the document to be signed, the list of required signers, the desired signature quality
        and legislation, and optional settings such as signing sequences, callback URLs, and
        access control.

        Upon creation, invitations are sent to all specified signers. The response contains
        the created `SignatureRequest` including its unique `id`, which is required for all
        subsequent operations on this request.

        **Content size limits**:
        Very large inline document content is rejected by the gateway in front
        of the API before the request reaches it, returning a `403 Forbidden`
        response. This currently returns a plain body instead of the standard
        Problem+JSON error envelope used elsewhere in this API; a fix to align
        it is planned.
      operationId: createSignatureRequest
      security:
        - bearer: []
      requestBody:
        description: Request body to create a SignatureRequest object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSignatureRequest'
            examples:
              PDFBase64:
                $ref: '#/components/examples/PDFBase64'
              PDFFileURL:
                $ref: '#/components/examples/PDFFileURL'
              PDFExistingDoc:
                $ref: '#/components/examples/PDFExistingDoc'
              Sequences:
                $ref: '#/components/examples/Sequences'
              NASfirst:
                $ref: '#/components/examples/NASfirst'
              Callbacks:
                $ref: '#/components/examples/Callbacks'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponse'
              examples:
                Sample1:
                  $ref: '#/components/examples/Sample1'
                Sample2:
                  $ref: '#/components/examples/Sample2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenOrPayloadTooLarge'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      tags:
        - Signature Handling
      summary: List and find Signature Requests
      description: |-
        Returns all `SignatureRequest` objects that the current user has sufficient
        access rights to.


        **Filter**


        You can optionally filter results using one or more of the optional
        parameters.


        Filters search for an exact match of the corresponding field value. This
        means the filter is case-sensitive and will not match partial values. For
        example, _account_email=john.doe@skribble.com_ will only match a
        `SignatureRequest` where the `account_email` field is exactly
        john.doe@skribble.com and will not match another.john.doe@skribble.com.


        Exception: The `search` parameter searches for document titles that contain
        the search term.


        **Pagination**


        The result set can be controlled using the optional pagination parameters
        `page_number` and `page_size`, which helps prevent excessively large result
        sets.
      operationId: getSignatureRequest
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureAccountMail'
        - $ref: '#/components/parameters/SignerEmailAddress'
        - $ref: '#/components/parameters/SignatureSearch'
        - $ref: '#/components/parameters/SignatureStatusCode'
        - $ref: '#/components/parameters/SignatureStatusOverall'
        - $ref: '#/components/parameters/SignaturesCount'
        - $ref: '#/components/parameters/CreatedBy'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: List of Signature Requests.
                items:
                  $ref: '#/components/schemas/SignatureResponse'
              examples:
                default:
                  $ref: '#/components/examples/SampleArray'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags:
        - Signature Handling
      summary: Update a Signature Request
      description: |-
        Updates an existing `SignatureRequest`. We recommend creating the `SignatureRequest`
        with all necessary information upfront and using this endpoint only when changes are
        required.

        The following fields can be updated: `title`, `message`, `legislation`, `quality`,
        `signatures`, `cc_email_addresses`, `callback_success_url`, `callback_error_url`,
        `callback_update_url`, `custom`, `attach_on_success`, `read_access`, and `write_access`.

        **Updating signers**

        To add or remove signers, provide the complete desired state of the `signatures` array:

        - To add a signer, include the new entry alongside all existing signers.
        - To remove a signer, omit their entry from the array.

        > **Important:** Any signer not present in the `signatures` array will be removed.
        Changes to signers can only be made as long as none of the signers have already
        completed their signature.

        **Updating observers**

        To update the observer list, provide the complete desired state of the
        `cc_email_addresses` array. Pass `null` to leave the current observers unchanged.
      operationId: updateSignatureRequest
      security:
        - bearer: []
      requestBody:
        description: Request body to update a SignatureRequest object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSignatureRequest'
            examples:
              UpdateTitleAndMessage:
                summary: Update title and message
                value:
                  id: 4f43614a-de50-bfe1-2df3-4c881fc7840e
                  title: Example contract
                  message: Please sign this document!
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/bulk:
    post:
      tags:
        - Signature Handling
      summary: List Signature Requests by bulk
      description: |-
        Retrieves multiple `SignatureRequest` objects in a single call.

        Provide a JSON array of `SignatureRequest` IDs in the request body to specify which
        records to fetch. The response includes only the `SignatureRequests` that were
        successfully found. IDs that do not match any existing record are silently ignored.
      operationId: bulkGetSignatureRequests
      security:
        - bearer: []
      requestBody:
        description: Array of SignatureRequest IDs to retrieve.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
            examples:
              default:
                $ref: '#/components/examples/Request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: |-
                  List of found SignatureRequests. IDs not matching any existing record
                  are silently ignored and absent from the response.
                items:
                  $ref: '#/components/schemas/SignatureResponse'
              examples:
                default:
                  $ref: '#/components/examples/Response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}:
    get:
      tags:
        - Signature
        - Signature Handling
      summary: Get a Signature Request
      description: Fetches a `SignatureRequest` by its ID.
      operationId: getSignatureRequestDetails
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponse'
              examples:
                Sample1:
                  $ref: '#/components/examples/Sample1'
                Sample2:
                  $ref: '#/components/examples/Sample2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags:
        - Signature
      summary: Delete a Signature Request
      description: |-
        Deletes a `SignatureRequest` by its ID.

        **Important:** A `SignatureRequest` can only be deleted via the API if:

        1. the `SignatureRequest` has `status_overall=OPEN`, and

        2. the API user has sufficient rights on the `SignatureRequest`, e.g. when
        it was created by the API user.

        Deleting a `SignatureRequest` does not necessarily remove it from the
        system immediately.

        **WITHDRAWN**

        When the API user is the **owner** of the `SignatureRequest` and it is
        still in `status_overall=OPEN`, the `SignatureRequest` will be
        **WITHDRAWN**.

        This means the `SignatureRequest` will transition to
        `status_overall=WITHDRAWN` and all pending signatures will be marked with
        `status_code=WITHDRAWN`. Sign and read rights for all signers will be
        revoked, so invited signers can no longer read or sign the
        `SignatureRequest`.


        **REMOVE AS PARTICIPANT**

        When the API user is a participant but not the owner of the
        `SignatureRequest`, the `DELETE` request will only remove the API user as a
        participant.

        In this case, the system will remove the `SignatureRequest` and its related
        documents once the last remaining user deletes it via the [Skribble web
        application](https://my.skribble.com).


        **DELETING**

        When the API user is the last user with access rights to the
        `SignatureRequest` (e.g. after a **WITHDRAW**), the `SignatureRequest` and
        its related documents will be permanently removed from the system.
      operationId: deleteSignatureRequest
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/withdraw:
    post:
      tags:
        - Signature
      summary: Withdraw a Signature Request
      description: |-
        Withdraws a `SignatureRequest`, for example when signing becomes unnecessary
        or an error occurred during the invitation process. As the inviter, you can
        explicitly withdraw the `SignatureRequest`. This removes all signers and
        observers as participants and notifies them with a specified `message`.


        Similar to deletion, the `withdraw` action can only be executed if:


        - The `SignatureRequest` has `status_overall=OPEN`

        - The API user has sufficient rights on the `SignatureRequest`, such as
        when it was created by the API user.


        > **Note**
        > We recommend using the `delete` endpoint, which automatically determines
        > the appropriate action. For example, if the API user does not have
        > withdrawal rights, they may instead be removed as a participant, or the
        > document may be deleted directly.
        >
        > Use the `withdraw` endpoint specifically when you need to withdraw the
        > `SignatureRequest` while keeping it in Skribble.
      operationId: withdrawSignatureRequest
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      requestBody:
        description: Request body to withdraw a SignatureRequest object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawSignatureRequest'
            examples:
              Withdraw:
                summary: Withdraw with a message
                value:
                  message: The signature request is no longer required.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponse'
              examples:
                Sample1:
                  $ref: '#/components/examples/WithdrawSignatureResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/remind:
    post:
      tags:
        - Signature Handling
      summary: Remind Open Signers of a Signature Request
      description: |-
        In addition to the automatic signature reminders, manual reminders can also
        be initiated via the Skribble web application and also via the API.


        This allows for greater flexibility in managing signature requests, ensuring
        that important documents are signed promptly. By using both automatic and
        manual reminders, you can tailor your approach to suit the specific needs of
        your users or customers.


        **Limits**


        There is an hourly limit on the number of signature reminders that can be
        sent. This limit ensures that reminders are used responsibly and prevents
        excessive notifications. Generally, this restriction should not affect you
        if you use this feature appropriately. By adhering to this limit, you can
        effectively manage your signature requests without overwhelming your users
        or customers with frequent reminders.
      operationId: remindSignatureRequest
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/report:
    get:
      tags:
        - Signature Handling
      summary: Get Signature Request Report
      description: |-
        Provides the signature report for a specific signature request.

        By default, the report is returned as a human-readable, digitally signed
        PDF document. Optionally, the report format can be changed using the
        `type` query parameter (e.g. JSON or HTML).

        The report contains all relevant information about the signature process,
        including signatories, timestamps, and verification details. It serves as
        legally valid proof of the completed signing process and can be stored or
        shared for auditing, compliance, or record-keeping purposes.
      operationId: getSignatureReport
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/ReportType'
      responses:
        '200':
          description: OK
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureReport'
              examples:
                default:
                  $ref: '#/components/examples/SignatureReportResponse'
            text/html:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/callbacks:
    get:
      tags:
        - Signature Handling
      summary: Get callback details for a signature request
      description: |-
        Returns detailed information about the callbacks associated with a
        `SignatureRequest`. Use this endpoint to confirm whether a callback has been
        executed or to identify errors that occurred during the callback process.


        **Result**


        If no callbacks have been triggered yet, the response will be an empty
        array. Otherwise, it contains an array of `callback` objects that have
        already been executed.
      operationId: getSignatureRequestCallbacks
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureCallbacksResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/attachments:
    post:
      tags:
        - Signature Attachment
      summary: Add an attachment to a signature request
      description: |-
        Use this endpoint to provide supplementary documents (for example, Terms &
        Conditions or appendices) to participants of a `SignatureRequest`.

        Attachments are delivered to participants together with the
        `SignatureRequest`.

        **Content type limits**:
        The Skribble API accepts PDF files, image files, Microsoft Office files, and
        plain text files.

        Allowed content types:
        - application/pdf
        - application/x-tika-msoffice
        - application/x-tika-ooxml
        - application/msword
        - application/vnd.openxmlformats-officedocument.wordprocessingml.document
        - application/vnd.ms-word.document.macroEnabled.12
        - application/vnd.ms-excel
        - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
        - application/vnd.ms-excel.sheet.macroenabled.12
        - application/vnd.ms-powerpoint
        - application/vnd.openxmlformats-officedocument.presentationml.presentation
        - application/vnd.ms-powerpoint.presentation.macroEnabled.12
        - image/gif
        - image/jpeg
        - image/png
        - text/plain

        **Content size limits**:
        The maximum size of a single attachment is approximately 40 MB.
        The maximum request size is 60 MB. Exceeding it is rejected by the
        gateway in front of the API before the request reaches it, returning a
        `403 Forbidden` response. This currently returns a plain body instead
        of the standard Problem+JSON error envelope used elsewhere in this
        API; a fix to align it is planned.

        **Amount limits**:
        There is currently no limit on the number of attachments per
        SignatureRequest. Abuse of this service may result in enforced limits.
      operationId: createSignatureAttachment
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      requestBody:
        description: Request body to create a SignatureAttachment object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSignatureAttachmentRequest'
            examples:
              Attachment:
                summary: PDF attachment
                value:
                  filename: Attachment-1.pdf
                  content_type: application/pdf
                  content: SGVsbG8gd29ybGQh
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponse'
              examples:
                Attachment1:
                  $ref: '#/components/examples/CreateSignatureAttachmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenOrPayloadTooLarge'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/attachments/{ATTACHMENT_ID}/content:
    get:
      tags:
        - Signature Attachment
      summary: Get Signature Attachment content
      description: |-
        Downloads the content of the attachment identified by `ATTACHMENT_ID`
        for the `SignatureRequest` with the ID `SR_ID`.
      operationId: getSignatureAttachmentContent
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/AttachmentIDPath'
      responses:
        '200':
          description: Binary attachment content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/attachments/{ATTACHMENT_ID}:
    delete:
      tags:
        - Signature Attachment
      summary: Remove an attachment from a signature request
      description: |-
        Deletes the attachment identified by `ATTACHMENT_ID` from the
        `SignatureRequest` with the ID `SR_ID`.
      operationId: deleteSignatureAttachment
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/AttachmentIDPath'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/signatures:
    post:
      tags:
        - Signature Signer
      summary: Add an individual signer
      description: |-
        To add an individual signer, use the same parameters as when creating a
        SignatureRequest. The process is the same. By using `account_email`, you can
        add a signer who has a Skribble account. By using `signer_identity_data`,
        you can invite a No-Account-Signer to the SignatureRequest with the ID
        `{{SR_ID}}`.


        > 💡 Good to know  

        We recommend this approach of combining `signer_idendity_data` and
        `account_email` if you are unsure whether the user has a Skribble account.
        The benefit is that an existing Skribble user will afterwards find the
        SignatureRequest in the **To sign** section of their account on
        my.skribble.com.  

        Conversely, if you invite them using only `signer_identity_data`, the
        document will not appear in their Skribble account, even if they have an
        existing Skribble account. Instead, they will have to access the document
        using the specific link provided in their signature invitation email.
      operationId: addSignatureSigner
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
      requestBody:
        description: Request body to add a Signer
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureRecipient'
            examples:
              default:
                $ref: '#/components/examples/AddSignatureSigner'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/signatures/{SID}:
    delete:
      tags:
        - Signature Signer
      summary: Remove an individual signer
      description: |-
        Removes an individual signer from the `SignatureRequest`. Provide the
        SignatureRequest ID `SR_ID` and the Signature ID `SID` of the signer to
        remove.
      operationId: removeSignatureSigner
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/SignerIDPath'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/identification_evidence/{EVIDENCE_ID}/status:
    get:
      tags:
        - Identification
      summary: Get Identification Evidence Status
      description: |-
        Returns the current status of the identification evidence for the given
        `SignatureRequest` and `evidence_id`.

        **Requirements:**
        - The business must have identification evidence enabled. If it is not,
          the request fails with `403 Forbidden` (problem type `feature-not-enabled`).
        - The identification process must have been initiated (`evidence_id` is required,
          available in `signer_identity_data.evidence_id` of the `SignatureRequest` response).
      operationId: getIdentificationEvidenceStatus
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/EvidenceIDPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentificationEvidenceStatusResponse'
              examples:
                default:
                  $ref: '#/components/examples/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/identification_evidence/{EVIDENCE_ID}:
    get:
      tags:
        - Identification
      summary: Get Identification Evidence JSON
      description: |-
        Retrieves the full identification evidence record as JSON for the given
        `SignatureRequest` and `evidence_id`.

        **Requirements:**
        - The business must have identification evidence enabled. If it is not,
          the request fails with `403 Forbidden` (problem type `feature-not-enabled`).
        - The identification process must be completed (`evidence_id` is required).
      operationId: getIdentificationEvidenceJSON
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/EvidenceIDPath'
      responses:
        '200':
          description: |-
            Identification result for the completed identification process.
            The exact schema depends on the identification provider configuration and is available on request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentificationEvidenceResponse'
              examples:
                default:
                  $ref: '#/components/examples/EvidenceJSONResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/identification_evidence/{EVIDENCE_ID}/files:
    get:
      tags:
        - Identification
      summary: Get Identification Evidence Files
      description: |-
        Downloads all files related to the identification evidence as a ZIP archive.

        **Requirements:**
        - The business must have identification evidence enabled. If it is not,
          the request fails with `403 Forbidden` (problem type `feature-not-enabled`).
        - The identification process must be completed (`evidence_id` is required).
      operationId: getIdentificationEvidenceFiles
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/EvidenceIDPath'
      responses:
        '200':
          description: OK — ZIP archive containing all identification evidence files.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /signature-requests/{SR_ID}/identification_evidence/{EVIDENCE_ID}/jwt:
    get:
      tags:
        - Identification
      summary: Get Identification Evidence JWT
      description: |-
        Retrieves the signed JWT for the identification evidence. Useful for
        cryptographic verification or downstream integration purposes.

        **Requirements:**
        - The business must have identification evidence enabled. If it is not,
          the request fails with `403 Forbidden` (problem type `feature-not-enabled`).
        - The identification process must be completed (`evidence_id` is required).
      operationId: getIdentificationEvidenceJWT
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/SignatureIDPath'
        - $ref: '#/components/parameters/EvidenceIDPath'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                description: Signed JWT representing the identification evidence.
              examples:
                default:
                  $ref: '#/components/examples/EvidenceJWTResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /seal:
    post:
      tags:
        - Seal
      summary: Seal a Document with a Legal Entity Signature
      description: |-
        Uploads a document and affixes an electronic seal in a single call.

        Optionally, a visual signature can also be placed on the document.

        The response contains the `document_id` of the newly created sealed
        document, which can be used to retrieve it.
      operationId: sealDocument
      security:
        - bearer: []
      requestBody:
        description: Content base64-encoded in a JSON object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSealRequest'
            examples:
              Sample1:
                $ref: '#/components/examples/SealDoc'
              Sample2:
                $ref: '#/components/examples/SealVisual'
              Sample3:
                $ref: '#/components/examples/SealVisualCustom'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSealResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /documents:
    post:
      tags:
        - Document
      summary: Upload a Document
      description: |-
        Upload using a **Base64 encoded** file as `content`.

        **Content size limits**:
        Very large uploads are rejected by the gateway in front of the API
        before the request reaches it, returning a `403 Forbidden` response.
        This currently returns a plain body instead of the standard
        Problem+JSON error envelope used elsewhere in this API; a fix to align
        it is planned.
      operationId: uploadDocument
      security:
        - bearer: []
      requestBody:
        description: Request body to create a Document object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDocumentRequest'
            examples:
              Base64:
                $ref: '#/components/examples/Base64'
              FileURL:
                $ref: '#/components/examples/FileURL'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
              examples:
                default:
                  $ref: '#/components/examples/Sample'
                form:
                  $ref: '#/components/examples/SamplePDFForm'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenOrPayloadTooLarge'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      tags:
        - Document
      summary: List All Accessible Documents
      description: Returns an array of all accessible `Document` objects.
      operationId: getDocuments
      security:
        - bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: List of Documents.
                items:
                  $ref: '#/components/schemas/DocumentResponse'
              examples:
                default:
                  $ref: '#/components/examples/SampleDocumentArray'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /documents/{DOC_ID}:
    get:
      tags:
        - Document
      summary: Get Document Metadata
      description: Fetches the metadata for the `Document` identified by its ID.
      operationId: getDocumentMetadata
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/DocumentIDPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
              examples:
                default:
                  $ref: '#/components/examples/Sample'
                form:
                  $ref: '#/components/examples/SamplePDFForm'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags:
        - Document
      summary: Delete a Document
      description: |-
        Deletes a `Document` by its ID. Deletion behaves similarly to deleting a
        `SignatureRequest` and does not necessarily remove the object from the
        system immediately.

        If more than one participant is involved, the DELETE request only removes
        the current user from the `Document`.

        The system permanently removes the `Document` once the last user deletes it
        via the Skribble web application.

        **Async cascade note:** If the `Document`'s parent `SignatureRequest` was
        recently deleted, the server-side cascade that removes associated documents
        runs asynchronously. During this window the document is still listed by
        `GET /documents` but returns `403 Forbidden` on delete attempts. Retry
        after a few seconds — the document will either have been removed by the
        cascade or the delete will succeed.
      operationId: deleteDocument
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/DocumentIDPath'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /documents/{DOC_ID}/content:
    get:
      tags:
        - Document
      summary: Get Document Content
      description: |-
        Downloads the content of the document identified by its ID. Returns either
        a PDF binary or a JSON object containing a Base64-encoded PDF.
      operationId: getDocumentContent
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/DocumentIDPath'
      responses:
        '200':
          description: PDF or JSON with Base64-encoded PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentContentResponse'
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /documents/{DOC_ID}/pages/{PAGE_ID}:
    get:
      tags:
        - Document
      summary: Get Document Page Preview
      description: |-
        Returns a preview image for a specific page of the uploaded PDF document.
        Page numbering starts at **0** for the first page.

        > Use the optional `scale` parameter to control the preview size:
        > `scale=100` returns a full-size preview, while `scale=20` returns a
        > thumbnail.
      operationId: getDocumentPreview
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/DocumentIDPath'
        - $ref: '#/components/parameters/PageIDPath'
        - $ref: '#/components/parameters/ScaleFactor'
      responses:
        '200':
          description: Preview image
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /sendto:
    post:
      tags:
        - SendTo
      summary: Create a Send-To Request
      description: |-
        Starts the signing process by uploading the PDF document `content` and
        assigning it a `title`.

        ### Limited lifetime

        > Send-To objects and their related Documents and SignatureRequests are only
        > guaranteed for a **limited lifetime**.
        >
        > - A Send-To request that is not claimed by a user — i.e. where a user
        >   does not add the document to their list of documents to sign — is
        >   deleted automatically after one day.
        >
        > - All Send-To objects and their related Documents and SignatureRequest
        >   objects, regardless of status, are deleted automatically after 90 days.
      operationId: createSendTo
      security:
        - {}
      requestBody:
        description: Content can be sent directly as a file or base64-encoded in a JSON object
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - title
                - content
              properties:
                title:
                  type: string
                  description: Title of the document.
                  example: Document 1
                content:
                  type: string
                  format: binary
                  description: PDF file to upload.
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSendToRequest'
            examples:
              Base64Document:
                summary: Base64-encoded PDF
                value:
                  title: Document 1
                  content: SGVsbG8gd29ybGQh
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSendToResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /sendto/{SEND_TO_ID}/track:
    get:
      tags:
        - SendTo
      summary: Track a Send-To Request
      description: |-
        To call the `track` endpoint, you must include the value of the
        `access_code` field—received when creating the `Send-To` object—in the
        request header `X-Accesscode`.
      operationId: trackSendTo
      security:
        - {}
      parameters:
        - $ref: '#/components/parameters/XAccesscodeHeader'
        - $ref: '#/components/parameters/SendToIdPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackSendToResponse'
              examples:
                unclaimed:
                  $ref: '#/components/examples/SendToUnclaimed'
                claimed:
                  $ref: '#/components/examples/SendToClaimed'
                signed:
                  $ref: '#/components/examples/SendToSigned'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /sendto/{SEND_TO_ID}/download:
    get:
      tags:
        - SendTo
      summary: Download Send-To Document
      description: |-
        To call the `download` endpoint, you must include the value of the
        `access_code` field—received when creating the `Send-To` object—in the
        request header `X-Accesscode`.

        The response contains the originally provided PDF document in its current
        state, which may be signed, declined, withdrawn, or still open for signing.
        The current status can be retrieved using the `track` endpoint.
      operationId: downloadSendTo
      security:
        - {}
      parameters:
        - $ref: '#/components/parameters/XAccesscodeHeader'
        - $ref: '#/components/parameters/SendToIdPath'
      responses:
        '200':
          description: OK
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    format: byte
                    description: Base64-encoded document content.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /sendto/{SEND_TO_ID}:
    delete:
      tags:
        - SendTo
      summary: Delete a Send-To Request
      description: |-
        To call the `delete` endpoint, you must include the value of the
        `access_code` field—received when creating the `Send-To` object—in the
        request header `X-Accesscode`.

        This call deletes the involved `Send-To`, `Document`, and `SignatureRequest`
        objects regardless of the current `Send-To` state.
      operationId: deleteSendTo
      security:
        - {}
      parameters:
        - $ref: '#/components/parameters/XAccesscodeHeader'
        - $ref: '#/components/parameters/SendToIdPath'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /user/signature-qualities:
    get:
      tags:
        - User
      summary: Get Signature Quality Details for a User
      description: |-
        Returns the effective signature `quality` that will be applied when the
        given `username` signs a document.

        The resulting quality is determined by the combination of the requested
        `quality` and `legislation`, where `any` matches any legislation.

        For example, if you create a `SignatureRequest` with `quality=AES_MINIMAL`
        and `legislation=ZERTES`, this endpoint will indicate the final quality the
        user will sign with — typically `QES`, as `AES_MINIMAL` upgrades to `QES`
        when the user's settings allow it.
      operationId: getUserSignatureQualities
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/UserName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSignatureQualitiesResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSignatureQualitiesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /activities/signatures:
    get:
      tags:
        - Report
      summary: Get signature activities by business
      description: |
        Returns detailed signature `activities` for your business and its members within a specified date range.

        Use these parameters to filter for a specific time range.

        | **Parameter** | **Description** | **Mandatory** |
        | --- | --- | --- |
        | `start_date` | The start date of the range to fetch the signature `activities`.  Format: `yyyy-MM-dd.` | yes |
        | `end_date` | The end date of the range to fetch the signature `activities`.  Format: `yyyy-MM-dd.` | yes |

        ### **Pagination**

        The result set can be controlled using the optional pagination parameters `page` and `size`

        | **Parameter** | **Description** | **Mandatory** |
        | --- | --- | --- |
        | `page` | The page number to fetch the signature `activities`.  Must be a positive integer.  Default: 1 | no |
        | `size` | The size of the page to fetch the signature activities.  Must be a positive integer.  Default: 25  Maximum: 100 | no |
        | `sort` | The sort order of the signature activities. Can be `asc` or `desc`.  Default is `desc`. | no |

        ### **Response**

        The response contains the following information.

        **General**

        | **Field** | **Description** |
        | --- | --- |
        | `activities` | Array of `activities`. See the following subchapter _Activities_. |
        | `total_items` | Total items to fetch when paginating through all the pages. |
        | `total_pages` | Total pages to fetch when paginating through all the pages. |
        | `current_page` | Current page number. |
        | `size` | Size of the page. |

        **Activities**

        | **Field** | **Description** |
        | --- | --- |
        | `id` | The ID of the signature `activity`. |
        | `action` | The action type of a signature activity. Can be `signed` or `sealed`. |
        | `timestamp` | The timestamp of the signature activity. |
        | `signature_request_id` | The signature request ID. |
        | `cost_center` | The cost center of the signature paying party. This information might not necessarily be present. |
        | `initiator` | The initiator `user` of the signature `activity`. See the following subchapter _User_. |
        | `signer` | The signer `user` of the signature `activity`. See the following subchapter _User_. |

        **User**

        | **Field** | **Description** |
        | --- | --- |
        | `email` | The email of the `user`. |
        | `first_name` | The first name of the `user`. |
        | `last_name` | The last name of the `user`. |
        | `type` | The membership status of the `user` in relation to the business. Can be `api`, `external`, `member` or `unknown`. |
        | `mobile` | The mobile number of the user. |
      operationId: getActivitiesSignaturesByBusiness
      security:
        - bearer: []
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivitiesSignaturesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /management/health:
    get:
      tags:
        - Monitoring
      summary: System Health
      description: |-
        Returns the current health status of the Skribble API. Use this endpoint
        to monitor system availability and responsiveness.

        `status:UP` indicates that the system is operational.
      operationId: getSystemHealth
      security:
        - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemHealthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    LoginRequest:
      type: object
      required:
        - username
        - api-key
      properties:
        username:
          type: string
          description: The username of the users credentials to login
          example: add_your_api_name_here
        api-key:
          type: string
          description: The API key of the users credentials to login
          example: please_enter_your_password_here
    ProblemResponse:
      title: Problem
      type: object
      description: |-
        Error response envelope returned for all 4xx and 5xx responses with a JSON body.
        Follows a Problem+JSON-style shape. The `key` field is optional and only present
        for errors that carry a machine-readable code.
      required:
        - type
        - method
        - path
        - status
        - message
      properties:
        type:
          type: string
          format: uri
          description: |-
            URI identifying the problem category. The host of this URI depends on
            the environment the request was made against (e.g. `api.skribble.com`
            and `api.skribble.de` for the production regions; other environments
            use their respective hosts). Match on the path segment after `/problem/`
            rather than the full URI. Known values:

            - `https://api.skribble.com/problem/problem-with-message` — generic error with a message
            - `https://api.skribble.com/problem/entity-not-found` — requested resource does not exist
            - `https://api.skribble.com/problem/feature-not-enabled` — a required feature is not enabled for the business
            - `https://api.skribble.com/problem/constraint-violation` — request violates a domain constraint
            - `https://api.skribble.com/problem/parameterized` — parameterized error with details
            - `https://api.skribble.com/problem/limit-exceeded` — a usage limit was exceeded
          example: https://api.skribble.com/problem/problem-with-message
        method:
          type: string
          description: HTTP method of the failing request.
          example: POST
        path:
          type: string
          description: Request URI of the failing request.
          example: /v2/signature-requests
        status:
          type: integer
          description: HTTP status code, mirroring the response status line.
          example: 400
        key:
          type: string
          description: |-
            Optional machine-readable error key. Present for a subset of errors that carry
            a stable code. Prefer matching on this field over parsing `message`, which is
            not part of the stable contract.

            Known keys, grouped by category:

            Authentication (`403`):

            - `error.auth.token_expired`: the access token has expired
            - `error.auth.token_invalid`: the access token is malformed or otherwise invalid
            - `error.auth.credentials_invalid`: the supplied credentials were rejected

            Rate limiting (`429`):

            - `error.rate_limit.exceeded`: a generic rate limit was exceeded
            - `error.rate_limit.reminder`: the per-signature-request reminder limit was exceeded

            File upload / attachment (`400`):

            - `file.attachment.unsupported`: the uploaded attachment type is not supported
            - `file.malware.detected`: malware was detected in the uploaded file

            PDF processing (`400`):

            - `file.pdf.general_error`: the PDF could not be loaded (corrupt or unreadable)
            - `file.pdf.encryption.unknown_password`: the PDF is encrypted with an unknown password
            - `file.pdf.encryption.no_changes_allowed`: the PDF's signature permissions (DocMDP) do not allow the required changes
            - `file.pdf.encryption.unknown_permissions`: the PDF is encrypted with an unknown permissions type
            - `file.pdf.signature_verification.failed`: verification of an existing PDF signature failed

            Signature request (`400`):

            - `error.sr.last_document_cannot_be_removed`: the request would remove the only remaining document from the signature request; an SR must keep at least one document
          example: file.attachment.unsupported
        message:
          type: string
          description: Human-readable error message.
          example: Validation failed for JSON object
    SignatureStatusCode:
      title: Signature Status Code
      type: string
      description: |-
        The state of a signature.

        Possible values:
          - **OPEN** Waiting for the user to sign a signature.
          - **WAITING** The signer is waiting for a preceding signer in the sequence to complete.
          - **DECLINED** The user declined to sign.
          - **WITHDRAWN** The owner has withdrawn the signature request.
          - **SIGNED** The user signed the document.
          - **ERROR** A technical error occurred.
      enum:
        - OPEN
        - WAITING
        - DECLINED
        - WITHDRAWN
        - SIGNED
        - ERROR
      example: SIGNED
    SignatureStatusOverall:
      title: Signature Status Overall
      type: string
      description: |-
        Overall signing status of the document.

        Possible values:
          - **OPEN** At least one user has not signed or declined their signature yet.
          - **DECLINED** At least one user declined to sign. The signature request failed.
          - **WITHDRAWN** The owner has withdrawn the signature request.
          - **SIGNED** All users signed the document. The signature request was successfully completed.
          - **EXPIRED** The owner-set `expires_at` date has passed before all signers signed. Terminal status.
          - **ERROR** A technical error occurred. The signature request cannot be completed.
      enum:
        - OPEN
        - DECLINED
        - WITHDRAWN
        - SIGNED
        - EXPIRED
        - ERROR
      example: OPEN
    SignatureLegislation:
      title: Signature Legislation
      type: string
      description: |-
        Legislation under which the signatures are created. Required when `quality` is `QES` or `AES_MINIMAL`.

        | Legislation | Description |
        | --- | --- |
        | **ZERTES** | QES according to Swiss law. This is the **default**. |
        | **EIDAS** | QES according to EU law. |
      enum:
        - ZERTES
        - EIDAS
      example: ZERTES
    SignatureQuality:
      title: Signature Quality
      type: string
      description: |-
        Minimal quality of the signatures for this signature request.

        | Quality | Description |
        | --- | --- |
        | **QES** | Every signer must use QES. This is the **default** quality. Requires a `legislation` parameter. |
        | **AES_MINIMAL** | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a `legislation` parameter. |
        | **AES** | Every signer uses AES. |
        | **SES** | Every signer uses SES. |
        | **DEMO** | Every signer uses a DEMO signature with **no legal binding**. API demo users (`api_demo_example_*`) get this quality by default. |
        | **PART11** | Signers use a signature compliant with 21 CFR Part 11 regulations. |
      enum:
        - SES
        - AES
        - AES_MINIMAL
        - QES
        - DEMO
        - PART11
      example: QES
    SignatureLanguage:
      title: Signature Language
      type: string
      description: Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.
      enum:
        - en
        - de
        - fr
        - it
      default: en
    SignerIdentityDataResponse:
      title: Signer Identity Data in Response
      type: object
      description: Signer identity information returned as part of the SignatureRequest response.
      properties:
        email_address:
          type: string
          description: Email address of the no-account-signer.
          format: email
          example: nas@example.com
        first_name:
          type: string
          description: First name of the no-account-signer.
          example: John
        last_name:
          type: string
          description: Last name of the no-account-signer.
          example: Doe
        mobile_number:
          type: string
          description: |-
            Mobile number of the no-account-signer in E.164 format without the leading `+`:
            country code + area code + number, no spaces or special characters.
          example: '41791234567'
        language:
          $ref: '#/components/schemas/SignatureLanguage'
        identity_reference:
          type: string
          description: Customer-generated identifier for further identification of the signer.
          example: Internal-ID-012345
        identification_require_evidence:
          type: boolean
          description: If set, a new identification process is started to get fresh evidence records, even if the signer is already identified.
          example: true
        force_standard_qes:
          type: boolean
          description: |-
            If set to `true`, this signer is always identified via the standard QES flow and is never routed
            through Express QES, regardless of the business's Express QES setting or other identity flags such as
            `identification_require_evidence`.
          example: true
        provider:
          type: string
          description: Evidence provider used to verify the signer's identity.
          example: swisscom_ra_app
        evidence_id:
          type: string
          description: |-
            ID of the evidence records created during identification. Populated in the
            `SignatureRequest` response once the identification process has been completed.
          example: '700580648'
    VisualSignatureImage:
      title: Visual Signature Image
      type: object
      description: Visual signature image.
      required:
        - content
        - content_type
      properties:
        content:
          type: string
          description: Base64 encoded bytes of content.
          format: byte
          example: SGVsbG8gd29ybGQh
        content_type:
          type: string
          description: Content type of bytes sent in content. At the moment this MUST be image/png
          example: image/png
        content_size:
          type: integer
          format: int32
          description: Size of `content` in bytes. Calculated by the server.
          readOnly: true
          example: 3160
    VisualSignaturePosition:
      title: Visual Signature Position
      type: object
      properties:
        page:
          type: string
          description: |-
            Page number (0-indexed) where the signature appears.
            This is a String and not a number!
          example: '0'
        height:
          type: number
          description: Height of the signature in pixels.
          example: 70
        width:
          type: number
          description: Width of the signature in pixels.
          example: 150
        x:
          type: number
          description: X-coordinate (pixels from left) of signature.
          example: 350
        'y':
          type: number
          description: Y-coordinate (pixels from top) of signature.
          example: 240
        rotation:
          type: number
          description: |-
            Defines a rotation of the field content. 
            If used in context with a form field, then only the values 0, 90, 180, 270 are legal.
            Otherwise every value is legal. The rotation is applied counter clockwise.
          example: 0
    VisualSignatureResponse:
      title: Visual Signature Response
      type: object
      description: Visual signature placement information.
      properties:
        image:
          $ref: '#/components/schemas/VisualSignatureImage'
        position:
          description: Position where the signature should appear.
          $ref: '#/components/schemas/VisualSignaturePosition'
        positions:
          type: array
          description: List of additional positions where the signature should appear.
          items:
            $ref: '#/components/schemas/VisualSignaturePosition'
        form_field:
          type: string
          description: |
            Name of the form field in which the signature is placed. If multiple fields of this name are present in the document, all will be used. Takes precedence before positions.
          example: Signature1
        text:
          type: object
          description: Text displayed inside the form field.
          properties:
            content:
              type: string
              description: Content of the text field.
              example: Customer Signature
            font_name:
              type: string
              description: |
                Font name used. For PDF: all default PDF fonts or fonts already embedded in the document.
              example: Helvetica-Bold
            font_size:
              type: string
              description: Font size used.
              example: '12'
            font_color:
              type: string
              description: Font color as RGB value encoded in hex.
              example: '#ff0000'
    SignatureRecipientResponse:
      title: Signature Callbacks Response
      type: object
      properties:
        sid:
          type: string
          format: uuid
          example: 894a0240-e01a-2307-4376-0267c6a8d105
        status_code:
          $ref: '#/components/schemas/SignatureStatusCode'
        account_email:
          type: string
          format: email
          example: you@example.info
        signer_identity_data:
          $ref: '#/components/schemas/SignerIdentityDataResponse'
        sequence:
          type: integer
          format: int32
          example: -1
        notify:
          type: boolean
          description: |-
            Whether Skribble sends notification emails to this signer. When set to `false` together with
            `signer_identity_data.identity_reference`, the TAN-based email validation for No-Account-Signers (SES) is skipped.
          example: true
        signing_url:
          type: string
          format: uri
          description: |-
            A personalized signing URL for this specific signer, distinct from the top-level signing_url of the SignatureRequest.
            It points to the Skribble web application and will directly open the document for signing
            provided that the user is known to Skribble and is logged in.
            Otherwise, the user must login or register first to be able to see the document.

            When the user visits this URL, they will be forwarded to a special preview page of the PDF document and can start the signature process as usual.

            You can add the following query parameters to this signing_url. Skribble will respect these parameters and redirect the user to the provided URLs once the signature process is finished.

            Example: `https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e/cd16bd0802d146fd94ff736d7d7bf551?exitURL=https%3A%2F%2Fmy-app.com%2Fsigned&redirectTimeout=10`

            | Parameter | Type | Description |
            | --- | --- | --- |
            | `exitURL` | string (URL-encoded) | Optional URL to redirect after the signature process finished. Example: `https%3A%2F%2Fgoogle.com` |
            | `errorURL` | string (URL-encoded) | Optional URL to redirect in case of an error. Defaults to `exitURL`. Ignored if `exitURL` is not set. Example: `https%3A%2F%2Fbing.com` |
            | `declineURL` | string (URL-encoded) | Optional URL to redirect when the user declines. Defaults to `exitURL`. Ignored if `exitURL` is not set. |
            | `hidedownload` | boolean | Optional flag to hide the download button on the success screen. Requires `exitURL` to be set. Example: `true` |
            | `redirectTimeout` | integer | Optional seconds before auto-redirect after signing. Min 0 (instant), max 90. Default: 45. Example: `20` |
            | `lang` | string | Optional language code to display the signing page in a specific language. Supported values: `en` (default), `de`, `fr`. Example: `lang=fr` |
            | `overlay` | boolean | Optional flag to show or hide the Skribble overlay on the signing page. |
          example: https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e/cd16bd0802d146fd94ff736d7d7bf551
        decline_message:
          type: string
          description: The message provided by the signer when declining the signature request. Only present if the signer declined and provided a message.
        signed_at:
          type: string
          format: date-time
          description: Timestamp when this signer signed the document.
          example: '2025-10-09T12:15:30.000Z'
        signed_legislation:
          $ref: '#/components/schemas/SignatureLegislation'
          description: The legislation under which this signer's signature was created. Only present after signing.
        signed_quality:
          $ref: '#/components/schemas/SignatureQuality'
          description: The actual quality of this signer's signature. Only present after signing.
        last_viewed_at:
          type: string
          format: date-time
          description: Timestamp when this signer last viewed the document.
          example: '2025-10-09T12:10:00.000Z'
        language:
          type: string
          description: Language preference for this signer.
          example: en
        visual_signature:
          $ref: '#/components/schemas/VisualSignatureResponse'
    SignatureAttachment:
      title: Signature Attachment
      type: object
      properties:
        attachment_id:
          type: string
          format: uuid
          example: 8ed33046-3798-8c54-0b13-0820d0d6e121
        filename:
          type: string
          example: Attachment.pdf
    AttachOnSuccess:
      title: Attachment when signed
      type: array
      description: |-
        When a SignatureRequest has been signed by all signers, all signers and all observers are notified by email.
        Skribble provides the option to attach two types of attachments automatically to this email:
          - the signed document and
          - the signature protocol.

        This can be configured via the business settings, which can be used to define that these documents should generally
        be attached for all SignatureRequests created by business members.

        Alternatively it is possible to define the attachments on demand per SignatureRequest by using this field.
      items:
        type: string
        enum:
          - SIGNED_DOCUMENT
          - SIGNATURE_PROTOCOL
      example:
        - SIGNED_DOCUMENT
        - SIGNATURE_PROTOCOL
    SignatureResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 4f43614a-de50-bfe1-2df3-4c881fc7840e
        title:
          type: string
          example: Example contract
        message:
          type: string
          example: Please sign this document!
        document_id:
          type: string
          format: uuid
          example: 29eae6aa-5558-2ada-2870-d4e654c0da5c
        legislation:
          $ref: '#/components/schemas/SignatureLegislation'
        quality:
          $ref: '#/components/schemas/SignatureQuality'
        signing_url:
          type: string
          format: uri
          description: The URL for the SignatureRequest owner to view and manage the request in the Skribble web application. This URL is not intended for signers — each signer has their own dedicated signing_url within the signatures array.
          example: https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e
        status_overall:
          $ref: '#/components/schemas/SignatureStatusOverall'
        business:
          type: string
          example: biz-42b4c2fb9ee947778ba70bc0698c78f7
        signatures:
          type: array
          items:
            $ref: '#/components/schemas/SignatureRecipientResponse'
        cc_email_addresses:
          type: array
          items:
            type: string
            format: email
          example: []
        auto_delete_at:
          type: string
          format: date
          description: |-
            Server-managed date on which this signature request and its related documents are automatically
            deleted in line with the owning business's retention policy. Not directly settable by API clients.
            May be absent or `null` when no retention policy applies.
          example: '2026-04-21'
        expires_at:
          type: string
          format: date
          description: |-
            Owner-set expiry date for this signature request. When this date passes, the request
            transitions to `status_overall=EXPIRED`. Set via `expires_at` at create time.
            Absent or `null` when no owner-set expiry has been configured.
          example: '2026-12-31'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/SignatureAttachment'
          example: []
        attach_on_success:
          $ref: '#/components/schemas/AttachOnSuccess'
        custom:
          type: string
          description: Custom field for storing application-specific data related to this signature request.
          example: MyCustomvalue1,MyVal2
        owner:
          type: string
          example: api_demo_example
        read_access:
          type: array
          description: Users or API keys with read access to this signature request.
          items:
            type: string
          example:
            - persononetosign@external.net
            - api_demo_example
            - you@example.info
            - persontwotosign@external.net
        write_access:
          type: array
          description: Users or API keys with write access to this signature request.
          items:
            type: string
          example:
            - api_demo_example
        created_at:
          type: string
          format: date-time
          example: '2025-10-08T17:37:03.569Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-10-08T17:37:03.569Z'
        callback_success_url:
          type: string
          description: Callback URL called on overall success. See the request schema for supported placeholders and retry behaviour.
          format: uri
          example: https://mybiz.com/call/success
        callback_error_url:
          type: string
          description: Callback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.
          format: uri
          example: https://mybiz.com/call/error
        callback_update_url:
          type: string
          description: Callback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.
          format: uri
          example: https://mybiz.com/call/update
        callback_start_sign_url:
          type: string
          description: Callback URL called when a signer starts the signature process (only for Express QES). See the request schema for supported placeholders and retry behaviour.
          format: uri
          example: https://mybiz.com/call/start-sign
        callback_ident_pending_url:
          type: string
          description: Callback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.
          format: uri
          example: https://mybiz.com/call/ident-pending
        callback_ident_error_url:
          type: string
          description: Callback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.
          format: uri
          example: https://mybiz.com/call/ident-error
    SignerIdentityData:
      title: Signer Identity Data
      type: object
      description: Optional (no-account) signer identity information.
      properties:
        email_address:
          type: string
          format: email
          description: Email address of no-account-signer. Mandatory when `quality` is `SES`.
          example: no-account@skribble.com
        first_name:
          type: string
          description: First name of no-account-signer
          example: John
        last_name:
          type: string
          description: Last name of no-account-signer
          example: Doe
        mobile_number:
          type: string
          description: |-
            Mobile number of the no-account-signer in E.164 format without the leading `+`:
            country code + area code + number, no spaces or special characters.
          example: '41791234567'
        language:
          $ref: '#/components/schemas/SignatureLanguage'
        provider:
          type: string
          description: Evidence provider where Skribble can verify the signer's identity data.
          example: some-provider
        identity_reference:
          type: string
          description: |-
            Optional customer-generated identifier for further identification. When set together with `notify: false`,
            the TAN-based email validation for No-Account-Signers (SES) is skipped, allowing signers to sign directly
            without the Skribble TAN process.
          example: Internal-ID-012345
        identification_require_evidence:
          type: boolean
          description: |-
            (optional) if set, even if the signer is already identified, a new identification process is started to get fresh evidence records.
            Only supported when the signature request's quality is `QES` and Express QES is enabled for the business;
            otherwise the request fails with a validation error.
          example: true
        force_standard_qes:
          type: boolean
          description: |-
            (optional) if set to `true`, this signer is always identified via the standard QES flow and is never routed
            through Express QES, regardless of the business's Express QES setting or other identity flags such as
            `identification_require_evidence`.
          example: true
    VisualSignature:
      description: Visual signature placement information.
      oneOf:
        - type: object
          title: Single Position
          description: Use a single explicit position.
          required:
            - position
          properties:
            position:
              $ref: '#/components/schemas/VisualSignaturePosition'
            image:
              $ref: '#/components/schemas/VisualSignatureImage'
            positions:
              description: Must not be provided when position is used.
              readOnly: true
            form_field:
              description: Must not be provided when position is used.
              readOnly: true
        - type: object
          title: Multiple Positions
          description: Use multiple explicit positions.
          required:
            - positions
          properties:
            positions:
              type: array
              items:
                $ref: '#/components/schemas/VisualSignaturePosition'
            image:
              $ref: '#/components/schemas/VisualSignatureImage'
            position:
              description: Must not be provided when positions are used.
              readOnly: true
            form_field:
              description: Must not be provided when positions are used.
              readOnly: true
        - type: object
          title: Form Field
          description: Use a form field only.
          required:
            - form_field
          properties:
            form_field:
              type: string
              description: |
                Name of the form field in which the signature is placed. If multiple fields of this name are present in the document, all will be used.
            text:
              type: object
              description: Optional text to display inside the form field.
              properties:
                content:
                  type: string
                  description: Content of the text field.
                  example: Customer Signature
                font_name:
                  type: string
                  description: |
                    Font name to use. It is just a suggestion. For PDF: all default PDF fonts can be used or fonts which are already embedded in the document. If not specified, the default font of the form field will be used.
                  example: Helvetica-Bold
                font_size:
                  type: string
                  description: Font size to use. If not specified, the default size for the form field will be used.
                  example: '12'
                font_color:
                  type: string
                  description: Font color to use as RGB value encoded in hex. Defaults to black (#000000).
                  example: '#ff0000'
            image:
              $ref: '#/components/schemas/VisualSignatureImage'
            position:
              description: Must not be provided when form_field is used.
              readOnly: true
            positions:
              description: Must not be provided when form_field is used.
              readOnly: true
    SignatureRecipient:
      title: Signature Recipient
      type: object
      properties:
        account_email:
          type: string
          description: Optional signer account email address.
          format: email
          example: you@example.info
        sequence:
          type: number
          description: Optional signing order for this signer, starting at `1`. If no sequence is supplied, signers can sign in any order. When a number is set, Skribble enforces an ascending signing order across all signers, based on their `sequence` values.
          format: int32
          default: -1
          example: 1
        notify:
          type: boolean
          description: Whether to send a notification to this signer.
          default: true
          example: false
        language:
          $ref: '#/components/schemas/SignatureLanguage'
        signer_identity_data:
          $ref: '#/components/schemas/SignerIdentityData'
        visual_signature:
          $ref: '#/components/schemas/VisualSignature'
    UpdateSignatureRequest:
      title: Update Signature Request
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Unique ID of the signature request.
          format: uuid
          example: 4f43614a-de50-bfe1-2df3-4c881fc7840e
        title:
          type: string
          description: Title of the signature request.
          example: Example contract
        message:
          type: string
          description: Message sent to the other participants along with this signature request.
          example: Please sign this document!
        legislation:
          $ref: '#/components/schemas/SignatureLegislation'
        quality:
          $ref: '#/components/schemas/SignatureQuality'
        signatures:
          oneOf:
            - type: 'null'
              title: No signers
            - type: array
              title: Signers
              description: List of recipients required to sign the document.
              items:
                $ref: '#/components/schemas/SignatureRecipient'
        cc_email_addresses:
          oneOf:
            - type: 'null'
              title: No update
            - type: array
              title: Update in Observers
              description: Observer email addresses of users who are granted read access and to whom notifications are sent.
              items:
                type: string
                format: email
              example:
                - backoffice@company.com
                - info@company.com
        callback_success_url:
          type: string
          description: Callback-URL which is called on overall success.
          format: uri
          example: https://mybiz.com/call/success
        callback_error_url:
          type: string
          description: Callback-URL which is called in case of an error.
          format: uri
          example: https://mybiz.com/call/success
        callback_update_url:
          type: string
          description: Callback-URL which is called in case of an update.
          format: uri
          example: https://mybiz.com/call/success
        callback_start_sign_url:
          type: string
          description: Callback-URL which is called when a signer starts the signature process (only for Express QES).
          format: uri
          example: https://mybiz.com/call/start-sign
        callback_ident_pending_url:
          type: string
          description: Callback-URL which is called when the identification of a signer requires manual review.
          format: uri
          example: https://mybiz.com/call/ident-pending
        callback_ident_error_url:
          type: string
          description: Callback-URL which is called when the identification of a signer ends in an error.
          format: uri
          example: https://mybiz.com/call/ident-error
        attach_on_success:
          oneOf:
            - type: 'null'
              title: No update
            - $ref: '#/components/schemas/AttachOnSuccess'
        write_access:
          oneOf:
            - type: 'null'
              title: No update
            - type: array
              title: Specific write access
              description: Users or API keys with write access to this signature request.
              items:
                type: string
              example:
                - api_demo_example
    CreateSignatureRequestBase:
      title: Signature Request Properties
      type: object
      required:
        - title
      properties:
        title:
          type: string
          description: Title of the signature request.
          example: Example contract
        message:
          type: string
          description: Message sent to the other participants along with this signature request.
          example: Please sign this document!
        legislation:
          $ref: '#/components/schemas/SignatureLegislation'
        quality:
          $ref: '#/components/schemas/SignatureQuality'
        signatures:
          type: array
          description: |-
            List of recipients required to sign the document.

            It is possible to create a SignatureRequest where one or more invited participants won't need a
            Skribble account to sign the SignatureRequest. Those signers are called No-Account-Signers (NAS).

            To invite a No-Account-Signer (NAS), include an entry in the signatures array without an
            `account_email` and provide the signer's details using `signer_identity_data` instead.

            Each entry in the signatures array will be treated as a distinct identity. This means two entries
            with the same `signer_identity_data` are treated as two different identities and require that this
            person signs the document twice.

            Optionally you can combine `signer_identity_data` and `account_email` in your requests. In this case,
            the system checks first if there is a Skribble account with the specified e-mail address.
            If one is found the existing Skribble user will be invited to sign the document. Otherwise, the
            specified user in `signer_identity_data` will be invited to sign.

            > **Good to know**
            > We recommend combining `signer_identity_data` and `account_email` if you are unsure whether the
            > user has a Skribble account.
            > The benefit is that an existing Skribble user will afterwards find the SignatureRequest in the
            > "To sign" section of their account on my.skribble.com.
            > Conversely, if you invite them using only `signer_identity_data`, the document will not appear in
            > their Skribble account, even if they have one. Instead, they will have to access the document
            > using the specific link provided in their signature invitation email.

            Missing fields like first name and last name can easily be adjusted by the signer through the
            Skribble web client.
          items:
            $ref: '#/components/schemas/SignatureRecipient'
        cc_email_addresses:
          type: array
          description: |-
            Observer email addresses of users who are granted read access and to whom notifications are sent.
            Any email address is accepted, regardless of whether the recipient already has a Skribble account.
            If the observer does not yet have an account, they will need to create one to access the document.
          items:
            type: string
            format: email
          example:
            - backoffice@company.com
            - info@company.com
        callback_success_url:
          type: string
          format: uri
          description: |-
            Callback URL called via POST when all signers have signed (overall success).

            The URL supports the following placeholders, replaced with current SignatureRequest data before each call:
            - `SKRIBBLE_SIGNATURE_REQUEST_ID` — the SignatureRequest ID
            - `SKRIBBLE_DOCUMENT_ID` — the final signed document ID

            **Retry:** If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours.
            The endpoint can return a `Retry-After` header (seconds) to control the retry interval.
          example: https://mybiz.com/call/success?sr=SKRIBBLE_SIGNATURE_REQUEST_ID
        callback_error_url:
          type: string
          format: uri
          description: |-
            Callback URL called via POST when a signer declines or the SignatureRequest is withdrawn.

            The URL supports the following placeholders, replaced with current SignatureRequest data before each call:
            - `SKRIBBLE_SIGNATURE_REQUEST_ID` — the SignatureRequest ID
            - `SKRIBBLE_DOCUMENT_ID` — the most recent document ID

            **Retry:** If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours.
            The endpoint can return a `Retry-After` header (seconds) to control the retry interval.
          example: https://mybiz.com/call/error?sr=SKRIBBLE_SIGNATURE_REQUEST_ID
        callback_update_url:
          type: string
          format: uri
          description: |-
            Callback URL called via POST on any change to the SignatureRequest (e.g. one signer has signed).

            The URL supports the following placeholders, replaced with current SignatureRequest data before each call:
            - `SKRIBBLE_SIGNATURE_REQUEST_ID` — the SignatureRequest ID
            - `SKRIBBLE_DOCUMENT_ID` — the most recent document ID
            - `SKRIBBLE_SIGNATURE_ID` — the Signature ID (SID) of the signature just made

            **Retry:** If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours.
            The endpoint can return a `Retry-After` header (seconds) to control the retry interval.
          example: https://mybiz.com/call/update?sr=SKRIBBLE_SIGNATURE_REQUEST_ID&sig=SKRIBBLE_SIGNATURE_ID
        callback_start_sign_url:
          type: string
          format: uri
          description: |-
            Callback URL called via POST when a signer starts the signature process (only for Express QES).

            The URL supports the following placeholders, replaced with current SignatureRequest data before each call:
            - `SKRIBBLE_SIGNATURE_REQUEST_ID` — the SignatureRequest ID
            - `SKRIBBLE_DOCUMENT_ID` — the most recent document ID

            **Retry:** If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours.
            The endpoint can return a `Retry-After` header (seconds) to control the retry interval.
          example: https://mybiz.com/call/start-sign?sr=SKRIBBLE_SIGNATURE_REQUEST_ID
        callback_ident_pending_url:
          type: string
          format: uri
          description: |-
            Callback URL called via POST when the identification of a signer requires manual review.

            The URL supports the following placeholders, replaced with current SignatureRequest data before each call:
            - `SKRIBBLE_SIGNATURE_REQUEST_ID` — the SignatureRequest ID
            - `SKRIBBLE_DOCUMENT_ID` — the most recent document ID

            **Retry:** If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours.
            The endpoint can return a `Retry-After` header (seconds) to control the retry interval.
          example: https://mybiz.com/call/ident-pending?sr=SKRIBBLE_SIGNATURE_REQUEST_ID
        callback_ident_error_url:
          type: string
          format: uri
          description: |-
            Callback URL called via POST when the identification of a signer ends in an error.

            The URL supports the following placeholders, replaced with current SignatureRequest data before each call:
            - `SKRIBBLE_SIGNATURE_REQUEST_ID` — the SignatureRequest ID
            - `SKRIBBLE_DOCUMENT_ID` — the most recent document ID

            **Retry:** If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours.
            The endpoint can return a `Retry-After` header (seconds) to control the retry interval.
          example: https://mybiz.com/call/ident-error?sr=SKRIBBLE_SIGNATURE_REQUEST_ID
        custom:
          type: string
          description: Custom field for storing application-specific data related to this signature request.
          example: MyCustomvalue1,MyVal2
        expires_at:
          type: string
          format: date
          description: |-
            **Early access.** This field is available to opted-in businesses only. To request
            access, contact [support@skribble.com](mailto:support@skribble.com).

            Setting `expires_at` requires the signature-request expiry feature to be enabled
            for the business. If it is not, the request fails with `403 Forbidden`
            (problem type `feature-not-enabled`).

            Owner-set expiry date for this signature request (ISO 8601 date, e.g. `2026-12-31`).

            When set, the `SignatureRequest` transitions to `status_overall=EXPIRED` at the end of the
            given day if it has not been completed. `EXPIRED` is a terminal status.

            **Constraints**

            - Must be today or later.
            - Must be at most 6 months in the future.
            - If the owning business has a retention policy configured, `expires_at` must be at most
              one day before the configured retention deletion date.

            Omit or send `null` to leave the request without an owner-set expiry.
          example: '2026-12-31'
        attach_on_success:
          $ref: '#/components/schemas/AttachOnSuccess'
        creator:
          type: string
          description: Set a business member as the owner of this signature request, in addition to the API user.
          format: email
          example: some-member-of@your-business.com
        write_access:
          type: array
          description: Users or API keys with write access to this signature request.
          items:
            type: string
            format: email
          example:
            - john.doe@skribble.com
            - jane.doe@skribble.com
    CreateSignatureRequest:
      title: Create Signature Request
      oneOf:
        - title: Base64 Content
          description: Provide the document as Base64-encoded content.
          allOf:
            - type: object
              required:
                - content
              properties:
                content:
                  type: string
                  format: byte
                  description: Base64 encoded bytes of the document. Maximum document size is **112.5 MB** unencoded (**150 MB** Base64-encoded).
                  example: SGVsbG8gd29ybGQh
                content_type:
                  type: string
                  description: Content type of bytes sent in content. Currently, only application/pdf is supported.
                  example: application/pdf
            - $ref: '#/components/schemas/CreateSignatureRequestBase'
        - title: File URL
          description: Provide a publicly accessible URL for the document.
          allOf:
            - type: object
              required:
                - file_url
              properties:
                file_url:
                  type: string
                  format: uri
                  description: Publicly accessible URL for document download.
                  example: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
            - $ref: '#/components/schemas/CreateSignatureRequestBase'
        - title: Document ID
          description: Reference an existing document already uploaded to Skribble.
          allOf:
            - type: object
              required:
                - document_id
              properties:
                document_id:
                  type: string
                  description: Document ID of an existing document on Skribble.
                  example: 3648f61d-4194-455c-a0bc-1c438d2cd11b
            - $ref: '#/components/schemas/CreateSignatureRequestBase'
    PayloadTooLarge:
      type: string
      description: |-
        Plain-text or HTML body returned by the gateway in front of the API when
        a request is rejected for exceeding the maximum allowed size, before it
        reaches the API. Pending a fix to align this with the standard
        Problem+JSON envelope used elsewhere in this API.
    WithdrawSignatureRequest:
      title: Withdraw Signature Request
      type: object
      properties:
        message:
          type: string
          description: Withdraw message.
          minLength: 0
          maxLength: 2048
          example: The reason for withdrawing the signature.
    SignatureReport:
      title: Signature Report
      type: object
      properties:
        header:
          type: object
          description: Metadata and status information about the signature request
          properties:
            signatureRequestID:
              type: string
            skribbleLogo:
              oneOf:
                - type: string
                - type: 'null'
            title:
              type: string
            status:
              type: string
            signatureCount:
              type: integer
              minimum: 0
            signatureCountSigned:
              type: integer
              minimum: 0
            attachmentNames:
              type: string
        userList:
          type: array
          description: List of users involved in the signature process
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
              firstname:
                type: string
              lastname:
                type: string
              groupName:
                type: string
              email:
                oneOf:
                  - type: string
                  - type: 'null'
              mobile:
                type: string
              businessName:
                type: string
              userActions:
                type: array
                items:
                  type: object
                  required:
                    - name
                    - time
                  properties:
                    name:
                      type: string
                    ip:
                      oneOf:
                        - type: string
                        - type: 'null'
                    time:
                      type: string
                    quality:
                      oneOf:
                        - type: string
                        - type: 'null'
                    legislation:
                      oneOf:
                        - type: string
                        - type: 'null'
                    documentId:
                      oneOf:
                        - type: string
                        - type: 'null'
                    documentSha256:
                      oneOf:
                        - type: string
                        - type: 'null'
                    documentPageCount:
                      type: integer
                      minimum: 0
                      default: 0
                    documentSize:
                      type: integer
                      minimum: 0
                      default: 0
                    documents:
                      type: array
                      items:
                        type: object
                        properties:
                          documentId:
                            type: string
                          documentSha256:
                            type: string
                        required:
                          - documentId
                          - documentSha256
                      default: []
                    message:
                      oneOf:
                        - type: string
                        - type: 'null'
                    signatureId:
                      oneOf:
                        - type: string
                        - type: 'null'
                    signersAdded:
                      type: array
                      items:
                        type: string
                      default: []
                    signersRemoved:
                      type: array
                      items:
                        type: string
                      default: []
                    observersAdded:
                      type: array
                      items:
                        type: string
                      default: []
                    observersRemoved:
                      type: array
                      items:
                        type: string
                      default: []
                    delegatees:
                      type: array
                      items:
                        type: string
                      default: []
                    delegatedSignatureId:
                      oneOf:
                        - type: string
                        - type: 'null'
                    newSignatureIds:
                      type: array
                      items:
                        type: string
                      default: []
                    certificateSubject:
                      oneOf:
                        - type: string
                        - type: 'null'
                    certificateSerial:
                      oneOf:
                        - type: string
                        - type: 'null'
                    certificateIssuer:
                      oneOf:
                        - type: string
                        - type: 'null'
                    signatureImage:
                      oneOf:
                        - type: string
                        - type: 'null'
                    signerGroupsAdded:
                      type: array
                      items:
                        type: string
                      default: []
                    signerGroupsRemoved:
                      type: array
                      items:
                        type: string
                      default: []
                    signerGroupName:
                      oneOf:
                        - type: string
                        - type: 'null'
                    mabEvidenceId:
                      oneOf:
                        - type: string
                        - type: 'null'
        error:
          oneOf:
            - type: string
            - type: 'null'
    CallbackType:
      title: Callback Type
      type: string
      description: |-
        The type of this callback. 

        Possible values:
          - **SUCCESS** Is triggered when the document has been successfully signed by all parties involved.
          - **UPDATE** Is triggered on changes on the `SignatureRequest` object like when one person of all involved parties has signed.
          - **ERROR** Is triggered when a person declines the signature or when the `SignatureRequest` is withdrawn.
          - **START_SIGN** Is triggered when a person starts the signature process (only for Express QES).
          - **IDENT_PENDING** Is triggered when the identification of a person within a signature process requires manual review.
          - **IDENT_ERROR** Is triggered when the identification of a person within a signature process ended in an error.
      enum:
        - SUCCESS
        - UPDATE
        - ERROR
        - START_SIGN
        - IDENT_PENDING
        - IDENT_ERROR
      example: SUCCESS
    CallbackState:
      title: Callback State
      type: string
      description: |-
        The state of the callback.

        Possible values:
          - **OPEN** The callback request will be executed in the next execution cycle.
          - **COMPLETED** The callback request was executed successfully. The API received an HTTP 2xx success code in response.
          - **RESIGNATED** The callback request has been attempted `attempts` times but was unsuccessful. The API did not receive a valid HTTP 2xx response.
      enum:
        - OPEN
        - COMPLETED
        - RESIGNATED
      example: COMPLETED
    SignatureCallbacksResponse:
      title: Signature Callbacks in Response
      type: array
      items:
        type: object
        properties:
          signature_request_id:
            type: string
            description: Signature request's unique ID on Skribble.
            format: uuid
            example: b107da0e-db25-478a-8130-b85e6c57ae83
          type:
            $ref: '#/components/schemas/CallbackType'
          state:
            $ref: '#/components/schemas/CallbackState'
          url:
            type: string
            description: The called URL of this callback.
            format: uri
            example: http://ext-service:8080/callback_success
          attempts:
            type: integer
            description: The attempts this callback was carried out.
            format: int32
            example: 1
          messages:
            type: array
            description: Error messages in case that the callback failed.
            items:
              type: string
              description: HTTP response message in case that the API did not receive a HTTP 2xx success code.
            example:
              - Failed 404
              - Failed 500
          created_at:
            type: string
            description: The time at which the object was created.
            format: date-time
            example: '2025-10-08T17:37:03.569Z'
          updated_at:
            type: string
            description: The time at which the object was last changed.
            format: date-time
            example: '2025-10-08T17:37:03.569Z'
    CreateSignatureAttachmentRequest:
      title: Create Signature Attachment Request
      required:
        - filename
        - content_type
        - content
      type: object
      properties:
        filename:
          type: string
          description: File name of the attachment.
          example: Attachment-1.pdf
        content_type:
          type: string
          description: |-
            Content type of the attachment. Supported types:
            `application/pdf`, `application/x-tika-msoffice`, `application/x-tika-ooxml`,
            `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`,
            `application/vnd.ms-word.document.macroEnabled.12`, `application/vnd.ms-excel`,
            `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`,
            `application/vnd.ms-excel.sheet.macroenabled.12`, `application/vnd.ms-powerpoint`,
            `application/vnd.openxmlformats-officedocument.presentationml.presentation`,
            `application/vnd.ms-powerpoint.presentation.macroEnabled.12`,
            `image/gif`, `image/jpeg`, `image/png`, `text/plain`
          example: application/pdf
        content:
          type: string
          description: Base64 encoded bytes of the attachment.
          format: byte
          example: SGVsbG8gd29ybGQh
    IdentificationEvidenceStatusResponse:
      title: Identification Evidence Status Response
      type: object
      properties:
        id:
          type: integer
          description: Internal ID of the evidence record.
          example: 1
        transactionCode:
          type: string
          description: Unique transaction code for the identification process.
          example: '700580648'
        accountId:
          type: integer
          description: Internal account ID associated with the identification.
          example: 111
        workflowId:
          type: integer
          description: Internal workflow ID used for the identification process.
          example: 11
        status:
          type: string
          description: Current status of the identification process.
          enum:
            - COMPLETED
            - PENDING
            - FAILED
          example: COMPLETED
        pendingReview:
          description: Present if the identification is pending manual review, otherwise null.
          oneOf:
            - type: 'null'
            - type: string
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the identification was created.
          example: '2025-08-25T12:26:24.227Z'
        expiresAt:
          type: string
          format: date-time
          description: Timestamp when the identification evidence expires.
          example: '2025-08-26T12:26:24.226Z'
        startedAt:
          type: string
          format: date-time
          description: Timestamp when the identification process was started by the signer.
          example: '2025-08-25T12:26:27.134Z'
        completedAt:
          description: Timestamp when the identification process was completed. Null if not yet completed.
          oneOf:
            - type: 'null'
            - type: string
              format: date-time
          example: '2025-08-25T12:27:58.382Z'
        reviewedAt:
          description: Timestamp when the identification was reviewed. Null if not reviewed.
          oneOf:
            - type: 'null'
            - type: string
              format: date-time
    IdentificationEvidenceResponse:
      title: Identification Evidence Response
      type: object
      additionalProperties: true
    CreateSealRequest:
      title: Create Seal Request
      type: object
      required:
        - content
      properties:
        content:
          type: string
          format: byte
          description: Base64 encoded bytes of the document.
          example: U29tZUJhc2U2NEVuY29kZWRJbWFnZQ==
        account_name:
          type: string
          description: Account name of the seal contract that should be used. If your company own more than one seal and the field account_name is not given or empty, then the first given seal for the API user will be used for sealing.
          example: ais_demo_seal
        title:
          type: string
          description: Title of the document.
          example: Example contract
        visual_signature:
          oneOf:
            - type: 'null'
              title: No visual signature
            - $ref: '#/components/schemas/VisualSignature'
    CreateSealResponse:
      title: Create Seal Response
      type: object
      required:
        - document_id
      properties:
        document_id:
          type: string
          description: Generated document ID
          format: uuid
          example: 98ca4eda-11f7-da4a-72da-9db677f38280
    SignatureFormFieldPosition:
      title: Formfield Position
      type: object
      properties:
        page:
          type: string
          description: |-
            Page number (0-indexed) where the field appears.
            This is a String and not a number!
          example: '0'
        height:
          type: number
          description: Height of the field in pixels.
          example: 70
        width:
          type: number
          description: Width of the field in pixels.
          example: 150
        x:
          type: number
          description: X-coordinate (pixels from left) of field.
          example: 350
        'y':
          type: number
          description: Y-coordinate (pixels from top) of field.
          example: 240
        rotation:
          type: number
          description: |-
            Defines a rotation of the field content. 
            If used in context with a form field, then only the values 0, 90, 180, 270 are legal.
            Otherwise every value is legal. The rotation is applied counter clockwise.
          example: 0
    SignatureFormField:
      title: Signature Formfield
      type: object
      properties:
        name:
          type: string
          description: Signature Formfield name
          example: Signature1
        signed:
          type: boolean
          description: Signature status of Formfield
          default: false
          example: false
        positions:
          type: array
          description: List of positions where the Formfield is present
          items:
            $ref: '#/components/schemas/SignatureFormFieldPosition'
    DocumentResponse:
      title: Document Response
      type: object
      description: Document object Response.
      properties:
        id:
          type: string
          format: uuid
          example: 00000000-1212-9546-6542-323232323232
        parent_id:
          description: ID of the previous version of the Document object. As documents are immutable, every change will create a new version, which is connected by the parent_id.
          type: string
          format: uuid
          example: 12345678-1234-aaaa-ffff-0123456789af
        title:
          type: string
          example: Example contract PDF
        content_type:
          type: string
          example: application/pdf
        size:
          type: integer
          example: 29010
        page_count:
          type: integer
          example: 1
        page_width:
          type: integer
          example: 600
        page_height:
          type: integer
          example: 840
        signature_fields:
          type: array
          description: Optional detected Signature Formfields
          items:
            $ref: '#/components/schemas/SignatureFormField'
        owner:
          type: string
          example: api_demo_example
        read_access:
          type: array
          description: Users or API keys with read access to this document.
          items:
            type: string
          example:
            - api_demo_example
        write_access:
          type: array
          description: Users or API keys with write access to this document.
          items:
            type: string
          example:
            - api_demo_example
        created_at:
          type: string
          format: date-time
          example: '2099-12-12T12:12:12.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2099-12-12T12:12:12.000Z'
    UploadDocumentRequest:
      title: Upload Document Request
      allOf:
        - type: object
          required:
            - title
          properties:
            title:
              type: string
              description: Title of the document.
              example: Example contract PDF
            read_access:
              type: array
              description: Give specific users or API keys read access to this document.
              items:
                type: string
              example:
                - backoffice@company_a.com
                - api_demo_example
            write_access:
              type: array
              description: Give specific users or API keys write access to this document.
              items:
                type: string
              example:
                - api_demo_example
        - oneOf:
            - type: object
              title: Base64 Content
              description: Provide the document as Base64-encoded content.
              required:
                - content
              properties:
                content:
                  type: string
                  format: byte
                  description: Base64 encoded bytes of the document.
                  example: SGVsbG8gd29ybGQh
                content_type:
                  type: string
                  description: Content type of bytes sent in content. Currently, only application/pdf is supported.
                  example: application/pdf
            - type: object
              title: File URL
              description: Provide a publicly accessible URL for the document.
              required:
                - file_url
              properties:
                file_url:
                  type: string
                  format: uri
                  description: Publicly accessible URL for document download.
                  example: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
    DocumentContentResponse:
      title: Document Content Response
      type: object
      description: Document Content Response as JSON
      properties:
        content_type:
          type: string
          example: application/pdf
        content_size:
          type: integer
          example: 29010
        content:
          type: string
          format: byte
          description: Base64 encoded bytes of the document.
          example: U29tZUJhc2U2NEVuY29kZWRJbWFnZQ==
    CreateSendToRequest:
      title: Create Send-To Request
      required:
        - title
        - content
      type: object
      properties:
        title:
          type: string
          description: Title of the document.
          example: Document 1
        content:
          type: string
          description: Base64 Encoded Document.
          format: byte
          example: SGVsbG8gd29ybGQh
    CreateSendToResponse:
      title: Create Send-To Response
      type: object
      required:
        - url
        - id
        - access_code
      properties:
        url:
          type: string
          description: URL to claim document to get signed.
          format: uri
          example: https://my.skribble.com/sendto/8229873d-d7c7-4e2b-a8a3-3313532
        id:
          type: string
          description: Generated send-to document ID
          format: uuid
          example: 8229873d-d7c7-4e2b-a8a3-000003313532
        access_code:
          type: string
          description: Access code to be used in for endpoints.
          format: uuid
          example: b498e9d2-93f4-4380-b998-c44f467ae020
    TrackSendToResponse:
      title: TrackSendToResponse
      type: object
      required:
        - status
        - signers
        - creator
      properties:
        status:
          type: string
          description: Status of the Send-To request
          enum:
            - UNCLAIMED
            - EXPIRED
            - CLAIMED
            - SIGNING
            - SIGNED
            - WITHDRAWN
            - DECLINED
        creator:
          description: User who claimed the Send-To request
          oneOf:
            - type: string
            - type: 'null'
        signers:
          description: List of signers for the Send-To request
          oneOf:
            - type: array
              items:
                type: string
            - type: 'null'
    UserSignatureQualitiesResponse:
      title: User Signature Qualities Response
      type: object
      properties:
        qes:
          type: object
          properties:
            zertes:
              type: string
              description: Effective quality when requesting QES with ZERTES legislation.
              example: QES
            eidas:
              type:
                - string
                - 'null'
              description: Effective quality when requesting QES with eIDAS legislation. Null if not available for this user.
              example: QES
        aes_minimal:
          type: object
          description: Best possible quality, but AES at a minimum.
          properties:
            zertes:
              type: string
              description: Effective quality when requesting AES_MINIMAL with ZERTES legislation.
              example: QES
            eidas:
              type: string
              description: Effective quality when requesting AES_MINIMAL with eIDAS legislation.
              example: AES
        aes:
          type: object
          properties:
            any:
              type: string
              description: Effective quality when requesting AES with any legislation.
              example: AES
        ses:
          type: object
          properties:
            any:
              type: string
              description: Effective quality when requesting SES with any legislation.
              example: SES
    ActivitiesSignaturesUser:
      title: Activities Signatures User
      type: object
      properties:
        email:
          type: string
          format: email
          example: john.doe@skribble.com
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        type:
          type: string
          enum:
            - member
            - external
            - api
            - unknown
          example: member
        mobile:
          type: string
          example: '41791234567'
    ActivitiesSignaturesEntry:
      title: Activities Signatures by Business Entry
      type: object
      properties:
        _id:
          type: string
          example: 66f5c2c054dc55b710d27968
        action:
          type: string
          description: Action performed on the signature request
          example: SIGNED
        timestamp:
          type: string
          format: date-time
          example: '2024-01-31T13:59:11.382Z'
        signature_request_id:
          type: string
          description: ID of the related signature request
          example: baf85d34-6676-8592-a7aa-39fb0ea81622
        cost_center:
          description: Optional cost center
          oneOf:
            - type: 'null'
            - type: string
        initiator:
          $ref: '#/components/schemas/ActivitiesSignaturesUser'
        signer:
          $ref: '#/components/schemas/ActivitiesSignaturesUser'
        quality:
          $ref: '#/components/schemas/SignatureQuality'
        legislation:
          $ref: '#/components/schemas/SignatureLegislation'
    ActivitiesSignaturesResponse:
      title: Activities Signatures by Business Response
      type: object
      description: Paginated list of signature activities for the business.
      properties:
        total_pages:
          type: integer
          example: 8
        total_items:
          type: integer
          example: 377
        current_page:
          type: integer
          example: 1
        size:
          type: integer
          example: 50
        activities:
          type: array
          items:
            $ref: '#/components/schemas/ActivitiesSignaturesEntry'
    SystemHealthResponse:
      title: System Health Response
      type: object
      description: System Health.
      properties:
        status:
          type: string
          example: UP
        groups:
          type: array
          items:
            type: string
          example:
            - liveness readyness
  examples:
    Login:
      summary: API credentials
      value:
        username: add_your_api_name_here
        api-key: please_enter_your_password_here
    SampleArray:
      value:
        - id: 4f43614a-de50-bfe1-2df3-4c881fc7840e
          title: Sample document
          message: Please sign this document.
          document_id: 1ff0cf91-6b54-f3bd-bffb-8fcd5e799764
          legislation: ZERTES
          quality: QES
          signing_url: https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e
          status_overall: OPEN
          business: biz-5a2aea44ddea4f0531ebcdcbcedf873c
          signatures:
            - sid: e5ab7fba-e815-0f65-f437-7c78953a0b7d
              account_email: you@example.info
              sequence: -1
              status_code: OPEN
              notify: true
          cc_email_addresses: []
          attachments: []
          owner: api_demo_example
          read_access:
            - you@example.info
            - api_demo_example
          write_access:
            - api_demo_example
          created_at: '2025-10-15T07:47:01.223Z'
          updated_at: '2025-10-15T07:47:01.223Z'
        - id: 8c73215f-bf33-d8a9-90e5-1a5cd0b9273a
          title: Employment Contract
          message: Please review and sign your employment contract.
          document_id: 2aa9b2e7-3c21-4d7a-bf9c-6a1f6f5fcb98
          legislation: EIDAS
          quality: AES
          signing_url: https://my.skribble.com/view/8c73215f-bf33-d8a9-90e5-1a5cd0b9273a
          status_overall: OPEN
          business: biz-87c4d39afc6d471da7bcbf4f2e8ef931
          signatures:
            - sid: 5ad9f2c1-6a81-42af-9a6a-7c5adcb54e23
              account_email: alice@example.com
              sequence: 1
              status_code: SIGNED
              notify: true
              visual_signature:
                position:
                  x: 120
                  'y': 490
                  width: 150
                  height: 70
                  page: '2'
                  rotation: 0
                positions:
                  - x: 120
                    'y': 490
                    width: 150
                    height: 70
                    page: '2'
                    rotation: 0
            - sid: 19de3b41-9d65-4cb7-90ff-239b7a0eac12
              account_email: hr@examplecorp.com
              sequence: 2
              status_code: OPEN
              notify: true
              visual_signature:
                position:
                  x: 130
                  'y': 420
                  width: 155
                  height: 72
                  page: '2'
                  rotation: 0
                positions:
                  - x: 130
                    'y': 420
                    width: 155
                    height: 72
                    page: '2'
                    rotation: 0
          cc_email_addresses:
            - legal@examplecorp.com
          owner: api_demo_example
          read_access:
            - alice@example.com
            - hr@examplecorp.com
            - legal@examplecorp.com
            - api_demo_example
          write_access:
            - api_demo_example
          created_at: '2025-10-15T08:15:22.115Z'
          updated_at: '2025-10-15T08:15:22.115Z'
    PDFBase64:
      summary: Document - With Base64 document
      value:
        title: Example contract
        message: Please sign this document!
        content: SGVsbG8gd29ybGQh
        content_type: application/pdf
        signatures:
          - account_email: you@example.info
    PDFFileURL:
      summary: Document - From a public file URL
      value:
        title: Example contract
        message: Please sign this document!
        file_url: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
        signatures:
          - account_email: you@example.info
          - account_email: personOneToSign@external.net
    PDFExistingDoc:
      summary: Document - Referencing an uploaded document
      value:
        title: Example contract
        message: Please sign this document!
        document_id: 3648f61d-4194-455c-a0bc-1c438d2cd11b
        signatures:
          - account_email: you@example.info
          - account_email: personOneToSign@external.net
          - account_email: personTwoToSign@external.net
    Sequences:
      summary: Signature Sequences
      value:
        title: Example contract
        message: Please sign this document!
        content: SGVsbG8gd29ybGQh
        content_type: application/pdf
        quality: SES
        signatures:
          - account_email: first@example.com
            sequence: 1
          - account_email: second@example.com
            sequence: 2
          - account_email: third@example.com
            sequence: 3
          - account_email: fourth@example.com
            sequence: 4
    NASfirst:
      summary: NAS unless has an account
      value:
        title: Example contract
        message: Please sign this document!
        content: SGVsbG8gd29ybGQh
        content_type: application/pdf
        quality: SES
        signatures:
          - account_email: signer@skribble.com
            signer_identity_data:
              email_address: signer@skribble.com
    Callbacks:
      summary: With all callback Templates
      value:
        title: Example contract
        message: Please sign this document!
        content: SGVsbG8gd29ybGQh
        content_type: application/pdf
        signatures:
          - account_email: you@example.info
        callback_success_url: https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678
        callback_update_url: https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/update?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678
        callback_error_url: https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678
        callback_start_sign_url: https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/start-sign?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678
        callback_ident_pending_url: https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/ident-pending?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678
        callback_ident_error_url: https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/ident-error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678
    Sample1:
      summary: Sample one signer waiting for signature
      value:
        id: 4f43614a-de50-bfe1-2df3-4c881fc7840e
        title: Sample document
        message: Please sign this document.
        document_id: 1ff0cf91-6b54-f3bd-bffb-8fcd5e799764
        legislation: ZERTES
        quality: QES
        signing_url: https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e
        status_overall: OPEN
        business: biz-5a2aea44ddea4f0531ebcdcbcedf873c
        signatures:
          - sid: e5ab7fba-e815-0f65-f437-7c78953a0b7d
            account_email: you@example.info
            sequence: -1
            status_code: OPEN
            notify: true
        cc_email_addresses: []
        attachments: []
        owner: api_demo_example
        read_access:
          - you@example.info
          - api_demo_example
        write_access:
          - api_demo_example
        created_at: '2025-10-15T07:47:01.223Z'
        updated_at: '2025-10-15T07:47:01.223Z'
    Sample2:
      summary: Sample multiple signers with visual signatures where one has signed
      value:
        id: 8c73215f-bf33-d8a9-90e5-1a5cd0b9273a
        title: Employment Contract
        message: Please review and sign your employment contract.
        document_id: 2aa9b2e7-3c21-4d7a-bf9c-6a1f6f5fcb98
        legislation: EIDAS
        quality: AES
        signing_url: https://my.skribble.com/view/8c73215f-bf33-d8a9-90e5-1a5cd0b9273a
        status_overall: OPEN
        business: biz-87c4d39afc6d471da7bcbf4f2e8ef931
        signatures:
          - sid: 5ad9f2c1-6a81-42af-9a6a-7c5adcb54e23
            account_email: alice@example.com
            sequence: 1
            status_code: SIGNED
            notify: true
            visual_signature:
              position:
                x: 120
                'y': 490
                width: 150
                height: 70
                page: '2'
                rotation: 0
              positions:
                - x: 120
                  'y': 490
                  width: 150
                  height: 70
                  page: '2'
                  rotation: 0
          - sid: 19de3b41-9d65-4cb7-90ff-239b7a0eac12
            account_email: hr@examplecorp.com
            sequence: 2
            status_code: OPEN
            notify: true
            visual_signature:
              position:
                x: 130
                'y': 420
                width: 155
                height: 72
                page: '2'
                rotation: 0
              positions:
                - x: 130
                  'y': 420
                  width: 155
                  height: 72
                  page: '2'
                  rotation: 0
        cc_email_addresses:
          - legal@examplecorp.com
        owner: api_demo_example
        read_access:
          - alice@example.com
          - hr@examplecorp.com
          - legal@examplecorp.com
          - api_demo_example
        write_access:
          - api_demo_example
        created_at: '2025-10-15T08:15:22.115Z'
        updated_at: '2025-10-15T08:15:22.115Z'
    Request:
      summary: Array of SignatureRequest IDs to retrieve
      value:
        - abababab-a777-e8e8-e8e8-121212121212
        - bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf
        - cccccccc-1111-2222-3333-444444444444
        - dddddddd-dead-beef-cafe-999999999999
        - eeeeeeee-aaaa-bbbb-cccc-dddddddddddd
        - ffffaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - abababab-1234-5678-9abc-defdefdefdef
        - 12341234-aaaa-bbbb-cccc-123412341234
        - 99999999-8888-7777-6666-555555555555
        - abcdabcd-abcd-abcd-abcd-abcdabcdabcd
    Response:
      summary: Found SignatureRequests (unrecognised IDs are silently omitted)
      value:
        - id: abababab-a777-e8e8-e8e8-121212121212
          title: First example contract
          document_id: 1ff0cf91-6b54-f3bd-bffb-8fcd5e799764
          legislation: ZERTES
          quality: QES
          signing_url: https://my.skribble.com/view/abababab-a777-e8e8-e8e8-121212121212
          status_overall: OPEN
          business: biz-5a2aea44ddea4f0531ebcdcbcedf873c
          signatures:
            - sid: e5ab7fba-e815-0f65-f437-7c78953a0b7d
              account_email: you@example.info
              sequence: -1
              status_code: OPEN
              notify: true
          cc_email_addresses: []
          attachments: []
          owner: api_demo_example
          read_access:
            - you@example.info
            - api_demo_example
          write_access:
            - api_demo_example
          created_at: '2025-10-15T07:47:01.223Z'
          updated_at: '2025-10-15T07:47:01.223Z'
        - id: bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf
          title: Second example contract
          document_id: 2aa9b2e7-3c21-4d7a-bf9c-6a1f6f5fcb98
          legislation: ZERTES
          quality: QES
          signing_url: https://my.skribble.com/view/bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf
          status_overall: SIGNED
          business: biz-5a2aea44ddea4f0531ebcdcbcedf873c
          signatures:
            - sid: f1a2b3c4-d5e6-7890-abcd-ef1234567890
              account_email: colleague@example.info
              sequence: -1
              status_code: SIGNED
              notify: true
          cc_email_addresses: []
          attachments: []
          owner: api_demo_example
          read_access:
            - colleague@example.info
            - api_demo_example
          write_access:
            - api_demo_example
          created_at: '2025-10-14T09:00:00.000Z'
          updated_at: '2025-10-14T11:30:00.000Z'
    WithdrawSignatureResponse:
      summary: Sample after withdrawn
      value:
        id: 4f43614a-de50-bfe1-2df3-4c881fc7840e
        title: Sample document
        message: Please sign this document.
        document_id: 1ff0cf91-6b54-f3bd-bffb-8fcd5e799764
        legislation: ZERTES
        quality: QES
        signing_url: https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e
        status_overall: WITHDRAWN
        business: biz-5a2aea44ddea4f0531ebcdcbcedf873c
        signatures:
          - sid: e5ab7fba-e815-0f65-f437-7c78953a0b7d
            account_email: you@example.info
            sequence: -1
            status_code: OPEN
            notify: true
        cc_email_addresses: []
        attachments: []
        owner: api_demo_example
        read_access:
          - api_demo_example
        write_access:
          - api_demo_example
        created_at: '2025-10-15T07:47:01.223Z'
        updated_at: '2025-10-15T07:47:01.223Z'
    SignatureReportResponse:
      summary: Sample JSON signature report
      value:
        header:
          signatureRequestID: f6794d09-8a51-5d3d-34f7-a600213451db
          skribbleLogo: PHN2ZyB3aWR0aD0iODYiIGhlaWdodD0iNDciIHZpZXdCb3g9IjAgMCA4NiA0NyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICAgIDxwYXRoIGQ9Ik0wLjcyMzYzMyA0Ni42Nzc1SDcxLjIxMzdWMzkuNTI5M0gwLjcyMzYzM1Y0Ni42Nzc1WiIgZmlsbD0iI0ZGNTMxQSIvPgogICAgPHBhdGgKICAgICAgICBkPSJNNTYuNjczMiAyMi4zNjc3TDQzLjkyMjEgOS4yNTI4MUwzMS40MzU2IDIyLjE4MzFMMTguNzUyNSA5LjI2MDJMMCAyOC40MDgzTDYuMzQ5MDkgMzQuOTIxNEwxOC43NTI1IDIxLjk0NjhMMzEuNDM1NiAzNC44OTkzVjM0LjkyMTRMNDMuOTI5NyAyMS45MzIxTDU2LjY4MDggMzQuODg0NVYzNC45MjE0TDg2IDYuNTc5NjFMNzkuNzI2NSAwTDU2LjY3MzIgMjIuMzY3N1oiCiAgICAgICAgZmlsbD0iI0ZGNTMxQSIvPgogICAgPHBhdGggb3BhY2l0eT0iMC4zIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGNsaXAtcnVsZT0iZXZlbm9kZCIKICAgICAgICAgIGQ9Ik0xOC42ODI2IDIxLjg1NTRMNi4yODc4MyAzNC43NjQ5TDAgMjguMjUzTDEyLjQ2NiAxNS41MjkzTDE4LjY4MjYgMjEuODU1NFoiIGZpbGw9IiNGRjUzMUEiLz4KICAgIDxwYXRoIG9wYWNpdHk9IjAuMyIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiCiAgICAgICAgICBkPSJNNDMuOTU0IDIxLjg4MjJMMzEuNDM2NiAzNC44MTUzTDI1LjMzNTkgMjguNDc1NUwzNy44NzE4IDE1LjUyOTNMNDMuOTU0IDIxLjg4MjJaIiBmaWxsPSIjRkY1MzFBIi8+Cjwvc3ZnPgo=
          title: Test SES
          status: OPEN
          signatureCount: 1
          signatureCountSigned: 0
          attachmentNames: ''
        userList:
          - id: api_production_skribbleag_42b4_8
            firstname: Skribble AG
            lastname: ''
            groupName: ''
            email: ''
            mobile: ''
            businessName: Skribble AG
            userActions:
              - name: CREATED
                ip: 104.28.233.251
                time: 2025-04-08 09:31:31 GMT
                quality: ''
                legislation: ''
                documentId: ''
                documentSha256: ''
                documentPageCount: 0
                documentSize: 0
                documents:
                  - documentId: 15c89996-9a6c-5262-1b88-6f19ea5d5027
                    documentSha256: c49fac90f9120515528982a0150acb930b4c33921512c260fc6506ce8602ce10
                message: ''
                signatureId: ''
                signersAdded: []
                signersRemoved: []
                observersAdded: []
                observersRemoved: []
                delegatees: []
                delegatedSignatureId: null
                newSignatureIds: []
                certificateSubject: null
                certificateSerial: null
                certificateIssuer: null
                signatureImage: null
                signerGroupsAdded: []
                signerGroupsRemoved: []
                signerGroupName: null
                mabEvidenceId: null
              - name: REPORT_CREATED
                ip: 104.28.233.251
                time: 2026-01-22 07:46:39 GMT
                quality: ''
                legislation: ''
                documentId: ''
                documentSha256: ''
                documentPageCount: 0
                documentSize: 0
                documents: []
                message: ''
                signatureId: ''
                signersAdded: []
                signersRemoved: []
                observersAdded: []
                observersRemoved: []
                delegatees: []
                delegatedSignatureId: null
                newSignatureIds: []
                certificateSubject: null
                certificateSerial: null
                certificateIssuer: null
                signatureImage: null
                signerGroupsAdded: []
                signerGroupsRemoved: []
                signerGroupName: null
                mabEvidenceId: null
        error: null
    CreateSignatureAttachmentResponse:
      summary: Sample with attachment
      value:
        id: 4f43614a-de50-bfe1-2df3-4c881fc7840e
        title: Sample document
        message: Please sign this document.
        document_id: 1ff0cf91-6b54-f3bd-bffb-8fcd5e799764
        attachments:
          - attachment_id: 8ed33046-3798-8c54-0b13-0820d0d6e121
            filename: Attachment.pdf
    AddSignatureSigner:
      summary: Add Individual Signer
      value:
        account_email: single-signer@skribble.com
        signer_identity_data:
          email_address: single-signer@skribble.com
    StatusResponse:
      summary: Completed identification evidence status
      value:
        id: 1
        transactionCode: '700580648'
        accountId: 111
        workflowId: 11
        status: COMPLETED
        pendingReview: null
        createdAt: '2025-08-25T12:26:24.227Z'
        expiresAt: '2025-08-26T12:26:24.226Z'
        startedAt: '2025-08-25T12:26:27.134Z'
        completedAt: '2025-08-25T12:27:58.382Z'
        reviewedAt: null
    EvidenceJSONResponse:
      summary: Completed identification evidence JSON
      value:
        identFormat: 1.0.0
        transactionCode: '700580648'
        initialTransactionCode: '700580648'
        status: COMPLETED
        flaggedAsFraud: false
        forcedManualReview: false
        pidDeleted: false
        createdAt: '2025-08-25T12:26:24.227Z'
        updatedAt: '2025-08-25T12:27:58.382Z'
        transactionLog:
          - status: INITIATED
            timestamp: '2025-08-25T12:26:27.134Z'
          - status: COMPLETED
            timestamp: '2025-08-25T12:27:58.382Z'
    EvidenceJWTResponse:
      summary: Signed JWT of the identification evidence
      value: eyJhbGci3R[...]UtMDUifQ.eyJpZGVudEZ[...]MC4wI.NVJJA6z[...]hE5sE85Nko751w
    SealDoc:
      summary: Seal document
      value:
        account_name: ais_demo_seal
        content: U29tZUJhc2U2NEVuY29kZWRJbWFnZQ==
    SealVisual:
      summary: Seal document with default visual signature
      value:
        account_name: ais_demo_seal
        title: Example contract
        content: U29tZUJhc2U2NEVuY29kZWRJbWFnZQ==
        visual_signature:
          position:
            x: 364
            'y': 160
            width: 129
            height: 60
            page: '0'
    SealVisualCustom:
      summary: Seal document with custom visual signature
      value:
        account_name: ais_demo_seal
        title: Example contract
        content: U29tZUJhc2U2NEVuY29kZWRJbWFnZQ==
        visual_signature:
          position:
            x: 100
            'y': 200
            width: 150
            height: 70
            page: '1'
          image:
            content: U3RyaW5n
            content_type: image/png
    SampleDocumentArray:
      value:
        - id: 00000000-1212-9546-6542-323232323232
          title: Example contract PDF
          content_type: application/pdf
          size: 29010
          page_count: 1
          page_width: 600
          page_height: 840
          owner: api_demo_example
          read_access:
            - api_demo_example
          write_access:
            - api_demo_example
          created_at: '2099-12-12T12:12:12.000Z'
          updated_at: '2099-12-12T12:12:12.000Z'
        - id: 11111111-2222-3333-4444-555555555555
          title: Employee NDA Document
          content_type: application/pdf
          size: 48230
          page_count: 3
          page_width: 612
          page_height: 792
          owner: api_demo_example
          read_access:
            - api_demo_example
          write_access:
            - api_demo_example
          created_at: '2099-10-01T09:00:00.000Z'
          updated_at: '2099-10-02T11:45:00.000Z'
    Base64:
      summary: Base64-encoded content
      value:
        title: Example contract PDF
        content: SGVsbG8gd29ybGQh
        content_type: application/pdf
    FileURL:
      summary: Publicly accessible file URL
      value:
        title: Example contract PDF
        file_url: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
    Sample:
      summary: Sample PDF document
      value:
        id: 00000000-1212-9546-6542-323232323232
        title: Example contract PDF
        content_type: application/pdf
        size: 29010
        page_count: 1
        page_width: 600
        page_height: 840
        owner: api_demo_example
        read_access:
          - api_demo_example
        write_access:
          - api_demo_example
        created_at: '2099-12-12T12:12:12.000Z'
        updated_at: '2099-12-12T12:12:12.000Z'
    SamplePDFForm:
      summary: Sample PDF with signature fields
      value:
        id: 8e725b0d-379c-5fd7-e7b7-ff369ac0c497
        parent_id: 461a654e-a2f5-7511-9e80-544abd6216e8
        title: Employment Contract
        content_type: application/pdf
        size: 266626
        page_count: 3
        page_width: 596
        page_height: 843
        signature_fields:
          - name: Signature1
            signed: true
            positions:
              - x: 75
                'y': 470
                width: 112
                height: 52
                page: '2'
                rotation: 0
        owner: api_demo_example
        read_access:
          - api_demo_example
        write_access:
          - api_demo_example
        created_at: '2024-11-18T12:37:45.842Z'
        updated_at: '2024-11-18T12:37:45.842Z'
    SendToUnclaimed:
      summary: Send-To not yet claimed
      value:
        status: UNCLAIMED
        creator: null
        signers: null
    SendToClaimed:
      summary: Send-To claimed by a user
      value:
        status: CLAIMED
        creator: user@example.com
        signers: null
    SendToSigned:
      summary: Send-To fully signed
      value:
        status: SIGNED
        creator: user@example.com
        signers:
          - signer1@example.com
          - signer2@example.com
    UserSignatureQualitiesResponse:
      summary: Sample User Signature Qualities Response
      value:
        qes:
          zertes: QES
          eidas: null
        aes_minimal:
          zertes: QES
          eidas: AES
        aes:
          any: AES
        ses:
          any: SES
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: POST
            path: /v2/signature-requests
            status: 400
            message: Validation failed for JSON object
    NotAcceptable:
      description: Not acceptable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: POST
            path: /v2/signature-requests
            status: 406
            message: Content type not supported
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: POST
            path: /v2/signature-requests
            status: 429
            message: Too many requests
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: POST
            path: /v2/signature-requests
            status: 500
            message: Internal server error
    ServiceUnavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: POST
            path: /v2/signature-requests
            status: 503
            message: Service unavailable
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: GET
            path: /v2/signature-requests
            status: 401
            message: Unauthorized
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/problem-with-message
            method: GET
            path: /v2/signature-requests/4f43614a-de50-bfe1-2df3-4c881fc7840e
            status: 403
            message: Access denied
    ForbiddenOrPayloadTooLarge:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          examples:
            AccessDenied:
              value:
                type: https://api.skribble.com/problem/problem-with-message
                method: GET
                path: /v2/signature-requests/4f43614a-de50-bfe1-2df3-4c881fc7840e
                status: 403
                message: Access denied
            FeatureNotEnabled:
              value:
                type: https://api.skribble.com/problem/feature-not-enabled
                method: POST
                path: /v2/signature-requests
                status: 403
                message: '''expires_at'' is not supported. Feature is not enabled.'
        text/plain:
          schema:
            $ref: '#/components/schemas/PayloadTooLarge'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
          example:
            type: https://api.skribble.com/problem/entity-not-found
            method: GET
            path: /v2/signature-requests/00000000-0000-0000-0000-000000000000
            status: 404
            message: SignatureRequest not found
  parameters:
    SignatureAccountMail:
      name: account_email
      in: query
      description: Filter on the field `signatures[].account_email`
      required: false
      schema:
        type: string
        format: email
      example: john.doe@skribble.com
    SignerEmailAddress:
      name: signer_email_address
      in: query
      description: Filter on the field `signatures[].signer_email_address`
      required: false
      schema:
        type: string
        format: email
      example: john.doe@skribble.com
    SignatureSearch:
      name: search
      in: query
      description: Filter on the field `title` to search for documents containing the serach term.
      required: false
      schema:
        type: string
      example: text to find
    SignatureStatusCode:
      name: signature_status
      in: query
      description: Filter on the field `signatures[].status_code` with one of the valid Signature states
      required: false
      schema:
        $ref: '#/components/schemas/SignatureStatusCode'
    SignatureStatusOverall:
      name: status_overall
      in: query
      description: Filter on the field `status_overall` with one of the valid Signature states
      required: false
      schema:
        $ref: '#/components/schemas/SignatureStatusOverall'
    SignaturesCount:
      name: signatures_count
      in: query
      description: Filter on the field `signatures_count`
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 1000
      example: 0
    CreatedBy:
      name: created_by
      in: query
      description: Filter on the field `created_by`
      required: false
      schema:
        type: string
      example: api_demo_example
    PageNumber:
      name: page_number
      in: query
      description: Page number for pagination. By default pagination is disabled.
      required: false
      schema:
        type: number
        minimum: 1
      example: 1
    PageSize:
      name: page_size
      in: query
      description: Page size for pagination.
      required: false
      schema:
        type: number
        default: 50
        minimum: 0
      example: 25
    SignatureIDPath:
      name: SR_ID
      in: path
      description: Unique ID received when creating the Signature Request object
      required: true
      schema:
        type: string
        format: uuid
      example: cccccccc-4a6a-a958-a42e-6ea4172a378b
    ReportType:
      name: type
      in: query
      description: Format of the Report.
      required: false
      schema:
        type: string
        enum:
          - PDF
          - JSON
          - HTML
        default: PDF
    AttachmentIDPath:
      name: ATTACHMENT_ID
      in: path
      description: Unique ID returned when the Signature Attachment is created.
      required: true
      schema:
        type: string
        format: uuid
      example: 8ed33046-3798-8c54-0b13-0820d0d6e121
    SignerIDPath:
      name: SID
      in: path
      description: Unique ID of the signer
      required: true
      schema:
        type: string
        format: uuid
      example: 97db18c8-7ca1-35a2-9726-0b32771e4ac6
    EvidenceIDPath:
      name: EVIDENCE_ID
      in: path
      description: Unique ID of the identification evidence record, available in the `signer_identity_data.evidence_id` field of the SignatureRequest response once identification is complete.
      required: true
      schema:
        type: string
      example: '700580648'
    DocumentIDPath:
      name: DOC_ID
      in: path
      description: Unique ID received when creating the Document Request object
      required: true
      schema:
        type: string
        format: uuid
      example: f1e2d3c4-7b8a-4e6f-9d3b-123456789abc
    PageIDPath:
      name: PAGE_ID
      in: path
      description: Page ID of the document
      required: true
      schema:
        type: integer
      example: 0
    ScaleFactor:
      name: scale
      in: query
      description: The scaling factor for the image.
      required: false
      schema:
        type: number
        default: 100
        minimum: 0
      example: 20
    XAccesscodeHeader:
      name: X-Accesscode
      in: header
      description: Access code received when creating the Send-To object
      required: true
      schema:
        type: string
        format: uuid
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    SendToIdPath:
      name: SEND_TO_ID
      in: path
      description: Unique ID received when creating the Send-To object
      required: true
      schema:
        type: string
        format: uuid
      example: d98ae06a-3ae4-5cc5-c0a3-62b05901b84f
    UserName:
      name: username
      in: query
      description: Username to find
      required: false
      schema:
        type: string
        format: email
      example: john.doe@skribble.com
    StartDate:
      name: start_date
      in: query
      description: Start Date to find
      required: true
      schema:
        type: string
        format: date
      example: '2024-01-01'
    EndDate:
      name: end_date
      in: query
      description: End Date to find
      required: true
      schema:
        type: string
        format: date
      example: '2024-01-31'
    Page:
      name: page
      in: query
      description: Page for pagination.
      required: false
      schema:
        type: number
        default: 1
      example: 1
    Size:
      name: size
      in: query
      description: Page size for pagination.
      required: false
      schema:
        type: number
        default: 25
        maximum: 100
      example: 50
    Sort:
      name: sort
      in: query
      description: Sort order
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: desc
        example: desc
