openapi: 3.0.3
info:
  title: FileCap API
  description: >-
    Full FileCap public / integration API collection.


    Groups:

    - 1. Legacy API (JSP) – the historic endpoints invoked by mail plugins and
    3rd-party integrations. Each JSP forwards to a modern REST endpoint under
    `/FileCap/api/...`, but the JSP URL remains supported.

    - 2. Transfer – upload, validate, reply, connection check.

    - 3. Invite – send invites and pre-generate invite IDs.

    - 4. Settings – portal/plugin settings, password rules, verification
    options.

    - 5. Validation – sender / recipient / file / domain validators.

    - 6. Business Rules (DLP) – scan attachments and text against the policy
    engine.

    - 7. Block transfer – revoke / inspect transfers.

    - 8. Device registration – register and verify a device for API access.


    Set the `baseURL` variable to e.g. `https://filecap.example.com` (no
    trailing slash). All paths are appended after `/FileCap`.
  version: 1.0.0
  contact: {}
servers:
  - url: https://filecap.example.com
paths:
  /FileCap/process_upload.jsp:
    post:
      tags:
        - 1. Legacy API (JSP)
      summary: Upload files (process_upload.jsp)
      description: >-
        Upload one or more files in a single transfer. The body must be
        `multipart/form-data`.


        Forwards to `/FileCap/api/transfer/v1/send-outlook-transfer`. The
        response is plain text:

        - `true` on success.

        - `false|<ERROR_CODE>` on failure.


        **Field ordering**


        The server streams the multipart body and processes parts in the order
        they arrive. The `fileMetadata` field MUST be sent BEFORE the `file01`,
        `file02`, ... parts; when a file part is read the server looks up its
        expected size in the metadata list and rejects the upload with `File
        metadata required` (S3 storage) or a NullPointerException (FREE-tier
        portals) if the metadata has not yet been seen.


        **Known error codes**

        - `VIRUS_FOUND` – a virus was detected in one of the files; the transfer
        was cancelled.

        - `NO_RECIPIENT_GIVEN` – no recipients were supplied.

        - `FILETYPE_NOT_ALLOW` – file type is forbidden by MIME or extension
        policy.

        - `PASSWORD_MANDATORY_BUT_NOT_GIVEN` – password is required but missing.

        - `CANNOT_SEND_MAIL` – the FileCap server could not send mail (mail
        server / relay misconfiguration).

        - `API_KEY_INVALID` – the supplied APIKey is not valid.

        - `GENERAL_ERROR` – unknown error; check the server log for a stack
        trace.
      operationId: uploadFilesProcessUploadJsp
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                APIKey:
                  description: The FileCap server API key.
                  type: string
                  example: '{{apiKey}}'
                bcc0:
                  description: Optional BCC recipient (bcc0, bcc1, ...).
                  type: string
                  example: ''
                cc0:
                  description: Optional CC recipient (cc0, cc1, ...).
                  type: string
                  example: ''
                comment:
                  description: Message body for the transfer.
                  type: string
                  example: This is a test
                deviceApiKey:
                  description: >-
                    Optional; per-device API key when the integration is
                    registered as a device.
                  type: string
                  example: ''
                dontNotify:
                  description: >-
                    Optional; when true the FileCap server will NOT send a
                    notification e-mail to the recipient (the integrating system
                    must handle notifications).
                  type: string
                  example: 'true'
                downloadLoadable_value:
                  description: Optional; maximum number of file downloads.
                  type: string
                  example: '10'
                encryptMessage:
                  description: >-
                    Optional; when true the comment/message is encrypted (plain
                    text only).
                  type: string
                  example: 'true'
                file01:
                  description: >-
                    First file part. Use file01, file02, file03... for multiple
                    files. MUST appear AFTER the fileMetadata field in the
                    multipart body.
                  type: string
                  format: binary
                  example: ''
                file02:
                  description: Additional file part.
                  type: string
                  format: binary
                  example: ''
                fileMetadata:
                  description: >-
                    REQUIRED. JSON array describing every file part in the
                    transfer. One entry per file with `filename`, `mimetype` and
                    `size` (bytes). The `filename` MUST exactly match the
                    `filename` of the corresponding file part. IMPORTANT: this
                    field MUST appear in the multipart body BEFORE the file
                    parts (file01, file02, ...). The server streams the body and
                    uses fileMetadata to look up each file's expected size; on
                    S3 storage missing/late metadata produces 'File metadata
                    required'.
                  type: string
                  example: >-
                    [{"filename":"document.pdf","mimetype":"application/pdf","size":102400}]
                from:
                  description: Email address of the sender.
                  type: string
                  example: kees@example.com
                fromName:
                  description: Optional; display name of the sender.
                  type: string
                  example: Kees Janssen
                ids:
                  description: The transfer ID. Must be unique per transfer.
                  type: string
                  example: '263478632784632748237513'
                mobileNr:
                  description: >-
                    Optional; recipient mobile number when SMS verification is
                    used.
                  type: string
                  example: ''
                nameRec0:
                  description: Optional display name for rec0 (nameRec0, nameRec1, ...).
                  type: string
                  example: ''
                nrOfFilesInTransfer:
                  description: Optional; explicit number of files in the transfer.
                  type: string
                  example: ''
                password:
                  description: >-
                    Optional; mandatory when encryptMessage = true or when the
                    server policy requires a password.
                  type: string
                  example: test1234
                rec0:
                  description: >-
                    First TO recipient. Use rec0, rec1, rec2... for multiple
                    recipients.
                  type: string
                  example: kees@receiver.com
                rec1:
                  description: Additional TO recipient.
                  type: string
                  example: henk@receiver2.com
                storeDays_value:
                  description: Optional; how many days the transfer stays on the server.
                  type: string
                  example: '5'
                subject:
                  description: Subject of the transfer.
                  type: string
                  example: API Test
                useSmsTextAuthentication:
                  description: >-
                    Optional; when true the recipient must enter an SMS
                    verification code (recipient must have a mobileNr).
                  type: string
                  example: 'true'
                userAgent:
                  description: Optional; identifies the calling client.
                  type: string
                  example: MyPlugin
                version:
                  description: Optional; client version.
                  type: string
                  example: '1.0'
      responses:
        '200':
          description: ''
  /FileCap/invite.jsp:
    post:
      tags:
        - 1. Legacy API (JSP)
      summary: Send invite (invite.jsp)
      description: >-
        Send a FileCap invite to an external user. Forwards to
        `/FileCap/api/invite/old`.


        Response is plain text:

        - `true` on success.

        - `false|<ERROR_CODE>` on failure.


        Known error codes:

        - `CANNOT_SEND_MAIL` – mail server cannot process the message.

        - `CANNOT_ADD_INVITE_TO_DB` – server could not persist the invite ID.

        - `UNKNOWN_ERROR` – an exception was raised; check the server log.
      operationId: sendInviteInviteJsp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                deviceApiKey:
                  type: string
                  example: ''
                id:
                  type: string
                  example: iiiii26347863278463274823755
                message:
                  type: string
                  example: ''
                notify:
                  type: string
                  example: 'true'
                receiverEmail:
                  type: string
                  example: piet@company.com
                receiverMobileNr:
                  type: string
                  example: ''
                senderEmail:
                  type: string
                  example: kees@example.com
            examples:
              Send invite (invite.jsp):
                value:
                  APIKey: '{{apiKey}}'
                  deviceApiKey: ''
                  id: iiiii26347863278463274823755
                  message: ''
                  notify: 'true'
                  receiverEmail: piet@company.com
                  receiverMobileNr: ''
                  senderEmail: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/mailPluginSettings.jsp:
    post:
      tags:
        - 1. Legacy API (JSP)
      summary: Request mail plugin settings (mailPluginSettings.jsp)
      description: >-
        Request the FileCap server settings used by mail plugins (Outlook
        classic etc.). Forwards to `/FileCap/api/settings/outlook-windows`.


        Response is XML and contains plug-in configuration: maximum file size,
        allowed extensions, password policy, verification methods, branding,
        etc.
      operationId: requestMailPluginSettingsMailpluginsettingsJsp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                lang:
                  type: string
                  example: NL
                userAgent:
                  type: string
                  example: OutlookPlugin
                version:
                  type: string
                  example: '1.0'
            examples:
              Request mail plugin settings (mailPluginSettings.jsp):
                value:
                  APIKey: '{{apiKey}}'
                  lang: NL
                  userAgent: OutlookPlugin
                  version: '1.0'
      responses:
        '200':
          description: ''
  /FileCap/checkFile.jsp:
    post:
      tags:
        - 1. Legacy API (JSP)
      summary: Check if a file may be sent (checkFile.jsp)
      description: >-
        Verify – before uploading – whether a single file is allowed by the
        server policy (extension/MIME blocklists, sender restrictions). Forwards
        to `/FileCap/api/validate/file`.


        Response is plain text: `true` when allowed, `false|<ERROR_CODE>` when
        blocked.
      operationId: checkIfAFileMayBeSentCheckfileJsp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                fileID:
                  type: string
                  example: ''
                filename:
                  type: string
                  example: test.exe
                mime:
                  type: string
                  example: application/exe
                sender:
                  type: string
                  example: kees@example.com
            examples:
              Check if a file may be sent (checkFile.jsp):
                value:
                  APIKey: '{{apiKey}}'
                  fileID: ''
                  filename: test.exe
                  mime: application/exe
                  sender: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/checkTransfer.jsp:
    post:
      tags:
        - 1. Legacy API (JSP)
      summary: Show files in a transfer (checkTransfer.jsp)
      description: >-
        Inspect a transfer that was created earlier. Forwards to
        `/FileCap/api/validate/transfer`. Used by mail plugins to check the
        status / contents of a previously created transfer.
      operationId: showFilesInATransferChecktransferJsp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                deviceApiKey:
                  type: string
                  example: ''
                email:
                  type: string
                  example: ''
                id:
                  type: string
                  example: '263478632784632748237513'
            examples:
              Show files in a transfer (checkTransfer.jsp):
                value:
                  APIKey: '{{apiKey}}'
                  deviceApiKey: ''
                  email: ''
                  id: '263478632784632748237513'
      responses:
        '200':
          description: ''
  /FileCap/domainCheck.jsp:
    post:
      tags:
        - 1. Legacy API (JSP)
      summary: Check domain (domainCheck.jsp)
      description: >-
        Verify whether the sender domain is allowed to send to the recipient
        domain (whitelist / IP rules). Forwards to
        `/FileCap/api/validate/domain`. Response is plain text: `true` when
        allowed, `false|<ERROR_CODE>` otherwise.
      operationId: checkDomainDomaincheckJsp
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: piet@receiver.com
                sender:
                  type: string
                  example: kees@example.com
            examples:
              Check domain (domainCheck.jsp):
                value:
                  email: piet@receiver.com
                  sender: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/send-outlook-transfer:
    post:
      tags:
        - 2. Transfer
      summary: Send Outlook transfer (modern, JSON response)
      description: >-
        Modern Outlook plugin upload endpoint. `multipart/form-data` request,
        JSON response.


        **Field ordering**: the `fileMetadata` field MUST be sent BEFORE the
        file parts; the server streams the body and looks up each file's
        expected size in the metadata list as the file part arrives.


        Response:

        ```

        {
          "success": true,
          "value": { "transferId": "...", "generatedPassword": "..." },
          "errorMessage": null
        }

        ```

        On failure `success` is `false` and `errorMessage` contains the reason.
        Rate-limited per session (`SendOutlookTransfer`).
      operationId: sendOutlookTransferModernJsonResponse
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                APIKey:
                  description: FileCap server API key.
                  type: string
                  example: '{{apiKey}}'
                bcc0:
                  description: BCC recipient (bcc0..bccN).
                  type: string
                  example: ''
                cc0:
                  description: CC recipient (cc0..ccN).
                  type: string
                  example: ''
                comment:
                  type: string
                  example: This goes through the JSON endpoint.
                deviceApiKey:
                  description: Optional device API key.
                  type: string
                  example: ''
                dontNotify:
                  description: When true, FileCap suppresses recipient notifications.
                  type: string
                  example: 'false'
                encryptMessage:
                  description: >-
                    Optional; encrypts the message body (alias:
                    `useEncryption`).
                  type: string
                  example: 'false'
                file01:
                  description: >-
                    First file part. Use file01..fileNN. Place AFTER the
                    fileMetadata field.
                  type: string
                  format: binary
                  example: ''
                fileMetadata:
                  description: >-
                    REQUIRED. JSON array describing every file part. One entry
                    per file with `filename`, `mimetype` and `size` (bytes).
                    `filename` MUST match the file-part filename exactly.
                    IMPORTANT: must appear BEFORE the file parts in the
                    multipart body.
                  type: string
                  example: >-
                    [{"filename":"document.pdf","mimetype":"application/pdf","size":102400}]
                from:
                  description: >-
                    Sender e-mail (aliases: `fromEmail`, `senderEmail`,
                    `senderEmailAddress`).
                  type: string
                  example: kees@example.com
                fromName:
                  description: 'Optional sender display name (alias: `senderName`).'
                  type: string
                  example: Kees Janssen
                ids:
                  description: 'Transfer ID (alias: `transferId`).'
                  type: string
                  example: '263478632784632748237513'
                maxDaysToStore:
                  description: 'Retention in days (alias: `storeDays_value`).'
                  type: string
                  example: '5'
                maxDownloads:
                  description: 'Maximum download count (alias: `downloadLoadable_value`).'
                  type: string
                  example: '10'
                nrOfFilesInTransfer:
                  type: string
                  example: '1'
                password:
                  description: Optional transfer password.
                  type: string
                  example: ''
                rec0:
                  description: 'TO recipient (alias: `recipient`). Use rec0..recN.'
                  type: string
                  example: piet@receiver.com
                subject:
                  type: string
                  example: Modern API test
                useSmsTextAuthentication:
                  description: 'Enable SMS verification (alias: `enableToken`).'
                  type: string
                  example: 'false'
                userAgent:
                  type: string
                  example: MyIntegration/1.0
                verificationMethod1:
                  description: >-
                    Primary verification method – e.g. EMAIL_ACCESS_CODE, SMS,
                    PASSWORD.
                  type: string
                  example: ''
                verificationMethod2:
                  description: Optional secondary verification method.
                  type: string
                  example: ''
                version:
                  type: string
                  example: '1.0'
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/v1/send-outlook-transfer:
    post:
      tags:
        - 2. Transfer
      summary: Send Outlook transfer (legacy v1, text response)
      description: >-
        Plain-text variant of the Outlook upload (returns `true` /
        `false|ERROR_CODE`). This is the endpoint that `process_upload.jsp`
        forwards to; use it when you need the legacy text response style.


        **Field ordering**: the `fileMetadata` field MUST be sent BEFORE the
        file parts.
      operationId: sendOutlookTransferLegacyV1TextResponse
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                comment:
                  type: string
                  example: Legacy v1 endpoint
                file01:
                  description: File part. Place AFTER the fileMetadata field.
                  type: string
                  format: binary
                  example: ''
                fileMetadata:
                  description: >-
                    REQUIRED. JSON array describing every file part (filename,
                    mimetype, size). MUST be sent BEFORE the file parts.
                  type: string
                  example: >-
                    [{"filename":"document.pdf","mimetype":"application/pdf","size":102400}]
                from:
                  type: string
                  example: kees@example.com
                ids:
                  type: string
                  example: '263478632784632748237513'
                rec0:
                  type: string
                  example: piet@receiver.com
                subject:
                  type: string
                  example: API Test
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/validate-upload:
    post:
      tags:
        - 2. Transfer
      summary: Validate upload (pre-flight)
      description: >-
        Validate the metadata of an upload before sending bytes. Checks server
        quota, allowed extensions/MIME, max size, etc.


        Returns `ApiResult<Void>` (only `success` and `errorMessage`). The
        aliased path `/transfer/validateUpload` works as well.
      operationId: validateUploadPreFlight
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fileMetadataList:
                  type: array
                  items:
                    type: object
                    properties:
                      fileName:
                        type: string
                        example: report.pdf
                      fileSize:
                        type: number
                        example: 102400
                      mimeType:
                        type: string
                        example: application/pdf
                  example:
                    - fileName: report.pdf
                      fileSize: 102400
                      mimeType: application/pdf
                lang:
                  type: string
                  example: NL
            examples:
              Validate upload (pre-flight):
                value:
                  fileMetadataList:
                    - fileName: report.pdf
                      fileSize: 102400
                      mimeType: application/pdf
                  lang: NL
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/validate-files:
    post:
      tags:
        - 2. Transfer
      summary: Validate files
      description: >-
        Per-file validation. Returns `ApiResult<ValidateFilesResultModel>` with
        one entry per file, indicating whether it is allowed and – if not – the
        rule that was violated.
      operationId: validateFiles
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fileMetadataList:
                  type: array
                  items:
                    type: object
                    properties:
                      fileName:
                        type: string
                        example: clean.pdf
                      fileSize:
                        type: number
                        example: 1024
                      mimeType:
                        type: string
                        example: application/pdf
                  example:
                    - fileName: clean.pdf
                      fileSize: 1024
                      mimeType: application/pdf
                    - fileName: forbidden.exe
                      fileSize: 2048
                      mimeType: application/x-msdownload
                lang:
                  type: string
                  example: NL
            examples:
              Validate files:
                value:
                  fileMetadataList:
                    - fileName: clean.pdf
                      fileSize: 1024
                      mimeType: application/pdf
                    - fileName: forbidden.exe
                      fileSize: 2048
                      mimeType: application/x-msdownload
                  lang: NL
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/validate-recipient:
    post:
      tags:
        - 2. Transfer
      summary: Validate recipient
      description: >-
        Validate the sender / recipient combination against domain whitelists,
        IP allow-lists and `emailMaySend` / `emailMayReceive` rules.


        Response is `ApiResult<Void>`. Possible error messages:
        `VALIDATION_ERROR_DOMAIN_INVALID`, `VALIDATION_ERROR_EMAIL_ADDRESS`.
      operationId: validateRecipient
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                recipientEmailAddress:
                  type: string
                  example: piet@receiver.com
                senderEmailAddress:
                  type: string
                  example: kees@example.com
            examples:
              Validate recipient:
                value:
                  recipientEmailAddress: piet@receiver.com
                  senderEmailAddress: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/send-reply:
    post:
      tags:
        - 2. Transfer
      summary: Send reply
      description: >-
        Send a secure reply to an existing transfer. `multipart/form-data`
        request, JSON `ApiResult<SentTransferInfo>` response. Rate-limited
        (`SendReply`).


        **Field ordering**: when file parts are attached, the `fileMetadata`
        field MUST be sent BEFORE them.
      operationId: sendReply
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  example: Reply with attachments.
                file01:
                  description: Optional file part. Place AFTER the fileMetadata field.
                  type: string
                  format: binary
                  example: ''
                fileMetadata:
                  description: >-
                    REQUIRED when file parts are attached. JSON array describing
                    every file part (filename, mimetype, size). MUST appear
                    BEFORE the file parts in the multipart body.
                  type: string
                  example: >-
                    [{"filename":"reply.pdf","mimetype":"application/pdf","size":51200}]
                from:
                  type: string
                  example: piet@receiver.com
                ids:
                  description: ID of the original transfer being replied to.
                  type: string
                  example: '263478632784632748237513'
                replyToAll:
                  description: Reply to every recipient of the original transfer.
                  type: string
                  example: 'false'
                subject:
                  type: string
                  example: 'RE: API Test'
      responses:
        '200':
          description: ''
  /FileCap/api/transfer/checkConnection:
    post:
      tags:
        - 2. Transfer
      summary: Check connection
      description: >-
        Lightweight liveness probe. Always returns
        `ApiResult.success("connected")` when the FileCap portal is reachable.
      operationId: checkConnection
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
            examples:
              Check connection:
                value: {}
      responses:
        '200':
          description: ''
  /FileCap/api/invite:
    post:
      tags:
        - 3. Invite
      summary: Send invite (modern JSON)
      description: >-
        Modern JSON variant of the legacy `invite.jsp` flow. Accepts a list of
        invitees in a single call and returns `ApiResult<Void>`. Rate-limited at
        10 requests / minute.
      operationId: sendInviteModernJson
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
                deviceApiKey:
                  type: string
                  example: ''
                invitees:
                  type: array
                  items:
                    type: string
                    example: piet@company.com
                  example:
                    - piet@company.com
                    - jan@partner.com
                message:
                  type: string
                  example: Please upload the requested documents.
                sender:
                  type: object
                  properties:
                    emailAddress:
                      type: string
                      example: kees@example.com
                    name:
                      type: string
                      example: Kees Janssen
            examples:
              Send invite (modern JSON):
                value:
                  apiKey: '{{apiKey}}'
                  deviceApiKey: ''
                  invitees:
                    - piet@company.com
                    - jan@partner.com
                  message: Please upload the requested documents.
                  sender:
                    emailAddress: kees@example.com
                    name: Kees Janssen
      responses:
        '200':
          description: ''
  /FileCap/api/invite/old:
    post:
      tags:
        - 3. Invite
      summary: Send invite (legacy form, /invite/old)
      description: >-
        Direct call to the endpoint that `invite.jsp` forwards to. Returns
        plain-text `true` / `false|<ERROR_CODE>`.
      operationId: sendInviteLegacyFormInviteOld
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                deviceApiKey:
                  type: string
                  example: ''
                id:
                  type: string
                  example: iiiii26347863278463274823755
                message:
                  type: string
                  example: ''
                notify:
                  type: string
                  example: 'true'
                receiverEmail:
                  type: string
                  example: piet@company.com
                receiverMobileNr:
                  type: string
                  example: ''
                senderEmail:
                  type: string
                  example: kees@example.com
            examples:
              Send invite (legacy form, /invite/old):
                value:
                  APIKey: '{{apiKey}}'
                  deviceApiKey: ''
                  id: iiiii26347863278463274823755
                  message: ''
                  notify: 'true'
                  receiverEmail: piet@company.com
                  receiverMobileNr: ''
                  senderEmail: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/invite/generate-id:
    post:
      tags:
        - 3. Invite
      summary: Generate invite ID
      description: >-
        Pre-generate an invite ID (the value used in the `id` field of the
        legacy invite call, prefixed with `iiiii`). Returns `ApiResult<String>`.
        Aliased path: `/invite/generateInviteId`.
      operationId: generateInviteId
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
                deviceApiKey:
                  type: string
                  example: ''
                sender:
                  type: object
                  properties:
                    emailAddress:
                      type: string
                      example: kees@example.com
            examples:
              Generate invite ID:
                value:
                  apiKey: '{{apiKey}}'
                  deviceApiKey: ''
                  sender:
                    emailAddress: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/settings/getPasswordRules:
    post:
      tags:
        - 4. Settings
      summary: Password rules (detailed, JSON)
      description: >-
        Detailed description of the password requirements. Returns
        `ApiResult<PasswordRules>` with `enabled`, `title`, and an array of
        rules (each rule: `description`, `requirement`).
      operationId: passwordRulesDetailedJson
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
                lang:
                  type: string
                  example: NL
            examples:
              Password rules (detailed, JSON):
                value:
                  apiKey: '{{apiKey}}'
                  lang: NL
      responses:
        '200':
          description: ''
  /FileCap/api/settings/password-rules:
    get:
      tags:
        - 4. Settings
      summary: Password rules (GET, public)
      description: >-
        Public, unauthenticated GET version of the password rules endpoint. Same
        `ApiResult<PasswordRules>` body.
      operationId: passwordRulesGetPublic
      parameters:
        - name: lang
          in: query
          schema:
            type: string
            example: NL
      responses:
        '200':
          description: ''
  /FileCap/api/settings/getPasswordPolicy:
    post:
      tags:
        - 4. Settings
      summary: Password policy (short)
      description: >-
        Short summary of password requirements: minimum length, character
        classes, expiration, reuse policy.
      operationId: passwordPolicyShort
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
            examples:
              Password policy (short):
                value:
                  apiKey: '{{apiKey}}'
      responses:
        '200':
          description: ''
  /FileCap/api/settings/outlook-windows:
    post:
      tags:
        - 4. Settings
      summary: Mail plugin settings (XML, /outlook-windows)
      description: >-
        Path that `mailPluginSettings.jsp` forwards to. Returns the plug-in
        configuration as XML.
      operationId: mailPluginSettingsXmlOutlookWindows
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                lang:
                  type: string
                  example: NL
                userAgent:
                  type: string
                  example: OutlookPlugin
                version:
                  type: string
                  example: '1.0'
            examples:
              Mail plugin settings (XML, /outlook-windows):
                value:
                  APIKey: '{{apiKey}}'
                  lang: NL
                  userAgent: OutlookPlugin
                  version: '1.0'
      responses:
        '200':
          description: ''
  /FileCap/api/settings/recipient-verification-options:
    post:
      tags:
        - 4. Settings
      summary: Recipient verification options
      description: >-
        Lists the verification methods that can be applied to a transfer (e.g.
        `NONE`, `EMAIL_ACCESS_CODE`, `SMS`, `PASSWORD`) and which ones are
        mandatory by current policy.
      operationId: recipientVerificationOptions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
            examples:
              Recipient verification options:
                value:
                  apiKey: '{{apiKey}}'
      responses:
        '200':
          description: ''
  /FileCap/api/settings/app-settings:
    post:
      tags:
        - 4. Settings
      summary: App settings
      description: >-
        Generic settings bundle for client apps: enabled features, max upload
        size, branding, supported languages, etc. Returns
        `ApiResult<AppSettings>`.
      operationId: appSettings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
                lang:
                  type: string
                  example: NL
            examples:
              App settings:
                value:
                  apiKey: '{{apiKey}}'
                  lang: NL
      responses:
        '200':
          description: ''
  /FileCap/api/settings:
    get:
      tags:
        - 4. Settings
      summary: Web portal settings
      description: >-
        Returns `ApiResult<WebPortalSettings>` for the web portal (theme, locale
        options, feature flags). Allowed for portal types MAIN, SUB, FREE.
      operationId: webPortalSettings
      parameters:
        - name: lang
          in: query
          schema:
            type: string
            example: NL
      responses:
        '200':
          description: ''
  /FileCap/api/settings/is-shared-access-code-available:
    post:
      tags:
        - 4. Settings
      summary: Is shared access code available
      description: >-
        Returns a raw boolean (`true` / `false`) – not wrapped in `ApiResult` –
        indicating whether a shared access code has been configured for the
        given transfer.
      operationId: isSharedAccessCodeAvailable
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transferId:
                  type: string
                  example: '263478632784632748237513'
            examples:
              Is shared access code available:
                value:
                  transferId: '263478632784632748237513'
      responses:
        '200':
          description: ''
  /FileCap/api/validate/file:
    post:
      tags:
        - 5. Validation
      summary: Check file (form, /validate/file)
      description: >-
        Direct call to the path that `checkFile.jsp` forwards to. Validates a
        single file by name + MIME against the policy engine.
      operationId: checkFileFormValidateFile
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                fileID:
                  type: string
                  example: ''
                filename:
                  type: string
                  example: test.exe
                mime:
                  type: string
                  example: application/exe
                sender:
                  type: string
                  example: kees@example.com
            examples:
              Check file (form, /validate/file):
                value:
                  APIKey: '{{apiKey}}'
                  fileID: ''
                  filename: test.exe
                  mime: application/exe
                  sender: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/validate/transfer:
    post:
      tags:
        - 5. Validation
      summary: Check transfer (/validate/transfer)
      description: Direct call to the path that `checkTransfer.jsp` forwards to.
      operationId: checkTransferValidateTransfer
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                deviceApiKey:
                  type: string
                  example: ''
                email:
                  type: string
                  example: ''
                id:
                  type: string
                  example: '263478632784632748237513'
            examples:
              Check transfer (/validate/transfer):
                value:
                  APIKey: '{{apiKey}}'
                  deviceApiKey: ''
                  email: ''
                  id: '263478632784632748237513'
      responses:
        '200':
          description: ''
  /FileCap/api/validate/domain:
    post:
      tags:
        - 5. Validation
      summary: Check domain (/validate/domain)
      description: Direct call to the path that `domainCheck.jsp` forwards to.
      operationId: checkDomainValidateDomain
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: piet@receiver.com
                sender:
                  type: string
                  example: kees@example.com
            examples:
              Check domain (/validate/domain):
                value:
                  email: piet@receiver.com
                  sender: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/validate/email-may-send:
    post:
      tags:
        - 5. Validation
      summary: Check sender may send (/validate/email-may-send)
      description: >-
        Returns a raw boolean (`true` / `false`) for the question "is this
        sender allowed to send via FileCap?". The body is the bare e-mail
        address as `text/plain`.
      operationId: checkSenderMaySendValidateEmailMaySend
      requestBody:
        content:
          text/plain:
            examples:
              Check sender may send (/validate/email-may-send):
                value: kees@example.com
      responses:
        '200':
          description: ''
  /FileCap/api/business-rules/scan-attachment:
    post:
      tags:
        - 6. Business Rules (DLP)
      summary: Scan attachment
      description: >-
        Run a DLP / business-rules scan against a single attachment. Returns
        `ApiResult<BusinessRulesScanResult>` with whether the file is allowed
        and any policy violations.
      operationId: scanAttachment
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                APIKey:
                  type: string
                  example: '{{apiKey}}'
                file:
                  description: Single file part to scan.
                  type: string
                  format: binary
                  example: ''
      responses:
        '200':
          description: ''
  /FileCap/api/business-rules/scan-text:
    post:
      tags:
        - 6. Business Rules (DLP)
      summary: Scan text
      description: >-
        Run a DLP scan against arbitrary text. Returns
        `ApiResult<BusinessRulesScanResult>`.
      operationId: scanText
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  example: >-
                    Hello, this is the message body that needs to be scanned for
                    sensitive data.
            examples:
              Scan text:
                value:
                  text: >-
                    Hello, this is the message body that needs to be scanned for
                    sensitive data.
      responses:
        '200':
          description: ''
  /FileCap/api/block/info:
    get:
      tags:
        - 7. Block transfer
      summary: Get block info
      description: >-
        Return the metadata that the FileCap web UI shows on the *block
        confirmation* page: the TO recipients of the transfer, the file names
        and a flag that indicates whether the message body was encrypted.


        **Response — `ApiResult<TransferBlockInfo>`**


        ```

        {
          "success": true,
          "value": {
            "recipients": ["piet@company.com", "jan@partner.com"],
            "files": ["contract.pdf", "appendix.docx"],
            "hasEncryptedMessage": false
          },
          "errorMessage": null
        }

        ```


        - `recipients` – array of e-mail addresses of the TO recipients of the
        transfer.

        - `files` – set of filenames (no path) inside the transfer.

        - `hasEncryptedMessage` – `true` when the message body of the transfer
        was encrypted at upload time.


        **Validation order** (every failure collapses to the generic error
        `PORTAL_BLOCK_TRANSFER_NOT_FOUND` unless noted otherwise):


        1. all three parameters must be non-blank;

        2. transfer with `transferId` must exist;

        3. SHA-hash of `blockId` must equal the transfer's stored
        `blockPassword`;

        4. `emailAddress` must be a known sender of that transfer;

        5. transfer must not be `DISABLED` (expired) — returns
        `PORTAL_DOWNLOAD_TRANSFER_EXPIRED`;

        6. transfer must not already be `BLOCKED` — returns
        `PORTAL_BLOCK_TRANSFER_ALREADY_BLOCKED`.


        This call is **read-only**: it does not modify the transfer, send any
        mail or write to the audit log.
      operationId: getBlockInfo
      parameters:
        - name: transferId
          in: query
          schema:
            type: string
            example: '263478632784632748237513'
          description: >-
            REQUIRED. The transfer's unique ID (the `ids` value from the upload
            call). Used to look up the transfer record.
        - name: blockId
          in: query
          schema:
            type: string
            example: BLK-1234
          description: >-
            REQUIRED. The block secret embedded in the FileCap notification mail
            to the sender (URL parameter `blockId` of `blockTransfer.jsp`). The
            server hashes this value and compares it with the `blockPassword`
            stored on the transfer.
        - name: emailAddress
          in: query
          schema:
            type: string
            example: kees@example.com
          description: >-
            REQUIRED. The e-mail address of the **sender** of the transfer.
            Validated against the sender record (`SenderDb.isSender(transfer,
            email)`). Not the recipient's address.
      responses:
        '200':
          description: ''
  /FileCap/api/block:
    post:
      tags:
        - 7. Block transfer
      summary: Block transfer
      description: >-
        Mark the transfer as blocked. After a successful call:


        - the transfer status is set to `BLOCKED` — subsequent download attempts
        (web portal or API) are refused;

        - an NTA audit-log entry is written: *user `<sender>` blocked transfer
        with id `<transferId>`*;

        - a *“message withdrawn”* notification mail is sent to all TO and CC
        recipients of the original transfer.


        **Request body (application/json)**


        | Field | Type | Required | Description |

        |---|---|---|---|

        | `transferId` | string | yes | The transfer's unique ID (the `ids`
        value from the upload call). |

        | `blockId` | string | yes | The block secret from the sender
        notification mail (`blockId` URL parameter of `blockTransfer.jsp`). The
        server hashes this and compares it to the stored `blockPassword`. |

        | `emailAddress` | string | yes | The **sender's** e-mail address.
        Validated against the transfer's sender record (`SenderDb.isSender`).
        Not the recipient address. |


        **Response — `ApiResult<Void>`**


        Only `success` and `errorMessage` are populated.


        **Possible error messages**


        | `errorMessage` | Meaning |

        |---|---|

        | `PORTAL_BLOCK_TRANSFER_NOT_FOUND` | Generic catch-all returned for
        missing parameters, unknown transfer, wrong `blockId`, wrong sender
        e-mail or any unexpected exception. The server deliberately does not
        distinguish these to avoid leaking which field was wrong. |

        | `PORTAL_DOWNLOAD_TRANSFER_EXPIRED` | The transfer has already expired
        (status `DISABLED`) and cannot be blocked. |

        | `PORTAL_BLOCK_TRANSFER_ALREADY_BLOCKED` | The transfer was blocked
        previously. |

        | `PORTAL_BLOCK_TRANSFER_ERROR` | The transfer record could not be
        updated (database error). |


        **Idempotency**


        A second call with the same parameters returns
        `PORTAL_BLOCK_TRANSFER_ALREADY_BLOCKED`; the underlying state is not
        changed and no extra notification mail is sent.


        **Side-effect ordering**


        The DB update happens before the notification mail is sent. If the mail
        server is unreachable the transfer is still blocked; the failure is only
        logged.
      operationId: blockTransfer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                blockId:
                  type: string
                  example: BLK-1234
                emailAddress:
                  type: string
                  example: kees@example.com
                transferId:
                  type: string
                  example: '263478632784632748237513'
            examples:
              Block transfer:
                value:
                  blockId: BLK-1234
                  emailAddress: kees@example.com
                  transferId: '263478632784632748237513'
      responses:
        '200':
          description: ''
  /FileCap/api/user/devices/register:
    post:
      tags:
        - 8. Device registration
      summary: Register device
      description: >-
        Initiate device registration. The server e-mails a verification code to
        `emailAddress`. Rate-limited (`RegisterDevice`).
      operationId: registerDevice
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  example: '{{apiKey}}'
                deviceName:
                  type: string
                  example: My integration server
                emailAddress:
                  type: string
                  example: kees@example.com
                lang:
                  type: string
                  example: NL
            examples:
              Register device:
                value:
                  apiKey: '{{apiKey}}'
                  deviceName: My integration server
                  emailAddress: kees@example.com
                  lang: NL
      responses:
        '200':
          description: ''
  /FileCap/api/user/devices/verify:
    post:
      tags:
        - 8. Device registration
      summary: Verify device
      description: >-
        Exchange the e-mailed verification code for a JWT / device token.
        Returns `ApiResult<String>`.
      operationId: verifyDevice
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: kees@example.com
                verificationCode:
                  type: string
                  example: '123456'
            examples:
              Verify device:
                value:
                  email: kees@example.com
                  verificationCode: '123456'
      responses:
        '200':
          description: ''
tags:
  - name: 1. Legacy API (JSP)
    description: >-
      Historic public API exposed through `.jsp` URLs. Each JSP performs a
      server-side forward to its modern `/api/...` counterpart.
      Backward-compatible: the JSP URL keeps working but new integrations should
      prefer the modern endpoints in the next folders.
  - name: 2. Transfer
    description: >-
      Modern transfer endpoints. The `/transfer/send-outlook-transfer` endpoint
      replaces the legacy `process_upload.jsp` flow but returns a structured
      JSON `ApiResult` instead of plain text. The
      `/transfer/v1/send-outlook-transfer` endpoint is the path the legacy JSP
      forwards to (text response).
  - name: 3. Invite
    description: >-
      Endpoints for sending FileCap invites (asking a 3rd party to upload files
      for you).
  - name: 4. Settings
    description: >-
      Server settings used by clients/plugins: password policy, recipient
      verification options, branding, plugin settings.
  - name: 5. Validation
    description: >-
      Lightweight validators that mail plugins can call before composing or
      sending a message. All endpoints return plain text (`true` /
      `false|<ERROR_CODE>`).
  - name: 6. Business Rules (DLP)
    description: >-
      Endpoints for the policy / DLP engine. Both endpoints require either
      DEVICE or API_KEY authentication and are rate-limited at 60 requests /
      minute.
  - name: 7. Block transfer
    description: >-
      **Sender-facing** endpoints to inspect and revoke (block) a transfer that
      has already been sent.


      ## How it works


      When a transfer is created, FileCap stores a hashed `blockPassword`
      together with the transfer and e-mails the **sender** a notification that
      contains a *block link* of the form:


      ```

      https://<host>/FileCap/blockTransfer.jsp?id=<transferId>&blockId=<blockId>&email=<senderEmail>

      ```


      `blockTransfer.jsp` sanitizes the parameters and redirects to the portal
      page `block`, which renders a confirmation screen. That page uses these
      two API endpoints under the hood:


      1. **`GET /api/block/info`** – load the metadata of the transfer to be
      blocked (recipients, file names, whether the message body is encrypted) so
      the sender can confirm what they are about to block.

      2. **`POST /api/block`** – actually mark the transfer as blocked. This
      stops further downloads, writes an audit-log entry (`blocked transfer`)
      and sends a *“message withdrawn”* notification to all TO and CC recipients
      of the original transfer.


      ## Authentication


      The `blockId` is the secret. The server hashes the value supplied by the
      caller and compares it to the `blockPassword` that was stored when the
      transfer was created. The combination of `transferId` + `blockId` +
      `emailAddress` (sender) acts as a capability — anyone holding all three
      can block the transfer; no API key or session is required.


      For security reasons every validation failure (wrong `blockId`, wrong
      sender, unknown transferId) collapses to the same generic error message
      `PORTAL_BLOCK_TRANSFER_NOT_FOUND`. The caller cannot tell which of the
      three was wrong.


      ## When integrating from a 3rd-party system


      If your integration suppresses FileCap's own notification mails
      (`dontNotify=true` on upload), it is responsible for forwarding the
      `blockId` from the upload response to the sender. Without that value the
      transfer cannot be blocked through the API.
  - name: 8. Device registration
    description: >-
      Endpoints for registering an external device (a 3rd party system) with the
      FileCap server so it can call the API with its own device key.
