Skribble Report API

openapi: 3.2.0
info:
  title: Skribble Report API
  contact:
    name: Skribble Engineering
    url: https://skribble.com
    email: support@skribble.com
  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/
  version: '1.0'
  description: 'Operations tagged Report across 3 of this provider''s published API definitions: skribble-sign-v3-openapi.yml, skribble-sign-v2-openapi.yml, skribble-sign-v3-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.skribble.com/v3
  description: Production - Switzerland
- url: https://api.skribble.de/v3
  description: Production - Germany
- url: https://api.skribble.com/v2
  description: Production - Switzerland
- url: https://api.skribble.de/v2
  description: Production - Germany
security: []
tags:
- name: Report
  description: Endpoints for signature activity reporting.
paths:
  /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'
    servers:
    - url: https://api.skribble.com/v3
      description: Production - Switzerland
    - url: https://api.skribble.de/v3
      description: Production - Germany
components:
  schemas:
    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
    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
    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'
    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'
    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
    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'
  responses:
    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
    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
    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
    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
    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:
    Sort:
      name: sort
      in: query
      description: Sort order
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
        example: desc
    EndDate:
      name: end_date
      in: query
      description: End Date to find
      required: true
      schema:
        type: string
        format: date
      example: '2024-01-31'
    Size:
      name: size
      in: query
      description: Page size for pagination.
      required: false
      schema:
        type: number
        default: 25
        maximum: 100
      example: 50
    Page:
      name: page
      in: query
      description: Page for pagination.
      required: false
      schema:
        type: number
        default: 1
      example: 1
    StartDate:
      name: start_date
      in: query
      description: Start Date to find
      required: true
      schema:
        type: string
        format: date
      example: '2024-01-01'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- skribble-sign-v3-openapi.yml
- skribble-sign-v2-openapi.yml
- skribble-sign-v3-openapi.yml