openapi: 3.1.0
info:
  title: Credentially Public Compliance-packages Documents API
  description: Public API Proxy with Rate Limiting and Audit
  version: 2.0.0
servers:
- url: https://app.credentially.io/gateway
  description: Generated server url
tags:
- name: Documents
  description: Document management proxy endpoints
paths:
  /api/documents/{profileId}:
    get:
      tags:
      - Documents
      summary: Get Profile Documents
      description: 'Fetches documents for a profile, enriched with extra OCR fields.


        **Rate Limit:** `get-documents` (100 req / 1s)'
      operationId: getDocuments
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentDto'
        '404':
          description: Documents or profile not found
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
    put:
      tags:
      - Documents
      summary: Upload Profile Document
      description: 'Uploads a document for a specific profile and triggers processing.


        **Rate Limit:** `get-documents` (100 req / 1s)'
      operationId: uploadDocument
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/DocumentUploadRequest'
                file:
                  type: string
                  format: binary
              required:
              - data
              - file
            encoding:
              data:
                contentType: application/json
      responses:
        '200':
          description: Document uploaded and processing started
        '400':
          description: Invalid request data
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
  /api/documents/reject:
    patch:
      tags:
      - Documents
      summary: Reject document of file.
      description: 'Decline specific document and file.


        **Rate Limit:** `reject-document` (5 req / 1s)'
      operationId: reject
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileRequest'
            encoding:
              note:
                contentType: application/json
        required: true
      responses:
        '200':
          description: Document declined successfully
        '400':
          description: Bad request, e.g. 'VerifierPublicId not found'
        '404':
          description: Document or file not found
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
  /api/documents/approve:
    patch:
      tags:
      - Documents
      summary: Approve document of file.
      description: 'Approve specific document and file.


        **Rate Limit:** `approve-document` (5 req / 1s)'
      operationId: approve_1
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileRequest'
            encoding:
              note:
                contentType: application/json
        required: true
      responses:
        '200':
          description: Document approved successfully
        '400':
          description: Bad request, e.g. 'VerifierPublicId not found'
        '404':
          description: Document or file not found
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
  /api/documents/download:
    get:
      tags:
      - Documents
      summary: Download file by its id
      description: 'Download file by its id.


        **Rate Limit:** `download-file` (5 req / 1s)'
      operationId: downloadFile
      parameters:
      - name: fileId
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      responses:
        '200':
          description: File downloaded successfully
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '500':
          description: File not found
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
  /api/documents/document-types:
    get:
      tags:
      - Documents
      summary: Get Organisation Document Types
      description: 'Fetches document types for an organisation.


        **Rate Limit:** `get-document-types` (100 req / 1s)'
      operationId: getDocumentTypes
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      responses:
        '200':
          description: Document types retrieved successfully
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganisationDocumentTypeDto'
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
components:
  schemas:
    DocumentTypeDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        key:
          type: string
        shortName:
          type: string
        ocrModelCode:
          type: string
        ocrModelName:
          type: string
        expiryPeriodInMonths:
          type: integer
          format: int32
        expireSoonPeriodInDays:
          type: integer
          format: int32
        category:
          type: string
        reminderText:
          type: string
        ocrSupported:
          type: boolean
        common:
          type: boolean
        profileOwnerRestricted:
          type: boolean
        ocrModel:
          type: object
          additionalProperties: {}
          writeOnly: true
    VerificationDto:
      type: object
      properties:
        verificationType:
          type: string
        note:
          type: string
        created:
          type: string
          format: date-time
        verifier:
          $ref: '#/components/schemas/UserSummaryDto'
    FileRequest:
      type: object
      description: 'Request body for approving/declining a file.

        ''documentPublicId'', ''fileId'' and ''organisationId'' are mandatory; ''note'' is mandatory only for rejecting.

        '
      properties:
        documentPublicId:
          type: string
        fileId:
          type: integer
          format: int64
        organisationId:
          type: integer
          format: int64
        note:
          type: string
        verifierPublicId:
          type: string
          description: 'The public Id from the profile that will be marked as the verifier on approval.

            This field is required when the session token is from a public-api (server-to-server).

            In other cases this parameter is not required and even ignored to use the id from the user in session.

            '
    UserSummaryDto:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        smallAvatarUrl:
          type: string
        roleName:
          type: string
        active:
          type: boolean
    OrganisationDocumentTypeDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        key:
          type: string
        shortName:
          type: string
        ocrModelCode:
          type: string
        ocrModelName:
          type: string
        expiryPeriodInMonths:
          type: integer
          format: int32
        expireSoonPeriodInDays:
          type: integer
          format: int32
        category:
          type: string
        reminderText:
          type: string
        ocrSupported:
          type: boolean
        common:
          type: boolean
        profileOwnerRestricted:
          type: boolean
        createdBy:
          type: string
        restrictAccessRoles:
          type: array
          items:
            $ref: '#/components/schemas/BaseRoleDto'
        approvalRoles:
          type: array
          items:
            $ref: '#/components/schemas/BaseRoleDto'
        ocrModel:
          type: object
          additionalProperties: {}
          writeOnly: true
    ActiveFileDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        publicId:
          type: string
        originName:
          type: string
        extraOcrFields:
          type: object
          additionalProperties: {}
        issued:
          type: string
          format: date
        expiry:
          type: string
          format: date
        monthToExpire:
          type: integer
          format: int32
        daysToExpire:
          type: integer
          format: int32
        created:
          type: string
          format: date-time
        issuesReason:
          type: string
        verifications:
          type: array
          items:
            $ref: '#/components/schemas/VerificationDto'
        actualVerificationStatuses:
          type: array
          items:
            $ref: '#/components/schemas/VerificationStatusDto'
        statusType:
          type: string
        uploader:
          $ref: '#/components/schemas/UserSummaryDto'
    VerificationStatusDto:
      type: object
      properties:
        status:
          type: string
        verifier:
          $ref: '#/components/schemas/UserSummaryDto'
        approvalRole:
          type: string
        verifiedDate:
          type: string
          format: date-time
    DocumentUploadRequest:
      type: object
      description: Request body for uploading a document.
      properties:
        uploaderId:
          type: string
          description: Mandatory profile ID of the uploader
          minLength: 1
        documentTypeKey:
          type: string
        otherDocumentTypeName:
          type: string
        skipDuplicates:
          type: boolean
      required:
      - uploaderId
    DocumentDto:
      type: object
      properties:
        id:
          type: string
        description:
          type: string
        type:
          $ref: '#/components/schemas/DocumentTypeDto'
        otherTypeName:
          type: string
        profileId:
          type: string
        versions:
          type: integer
          format: int32
        activeFile:
          $ref: '#/components/schemas/ActiveFileDto'
        statusType:
          type: string
    BaseRoleDto:
      type: object
      properties:
        roleId:
          type: integer
          format: int64
        roleName:
          type: string
  securitySchemes:
    bearer-key:
      type: http
      scheme: bearer
      bearerFormat: JWT