FileCap

Public API Reference

Integration & Mail Plugin Endpoints

1. Introduction

This document describes the public HTTP API exposed by the FileCap server. These endpoints are intended for email plugins, third-party integrations, and other external systems that need to upload files, request invites, validate transfer metadata, or read server configuration. Internal endpoints used by the admin panel, the OWA add-in, and partner/license server integrations are outside the scope of this document.

The API has evolved through two distinct generations:

1. Legacy API – a set of .jsp URLs (e.g., process_upload.jsp) that historically powered the Outlook Classic plugin and similar integrations. Each JSP performs a server-side redirect to a modern REST endpoint; both the JSP and the modern path continue to function.
2. Modern API – JSON / multipart endpoints under /FileCap/api/... that return a structured ApiResult<T> envelope. New integrations should target this interface.

1.1 Base URL & Context Root

All endpoints are served from the FileCap web application at the context root /FileCap. The Postman collection included with this document uses a baseURL variable that should contain the scheme and host (no trailing slash), e.g.:

https://filecap.example.com

The resulting URLs are then constructed as {{baseURL}}/FileCap/<path>.

1.2 Authentication

Most endpoints accept an APIKey in the request body (form field, URL-encoded parameter, or JSON property—the modern variants accept apiKey as well). The key is configured per FileCap tenant and is required for every integration call unless the endpoint is explicitly public (e.g., password-rules and the validate/* endpoints).

A subset of modern endpoints also accepts a deviceApiKey, returned by the device registration flow (section 9). Endpoints that require web portal authentication use either the portal session cookie or a JWT Bearer token (scope transfer:free).

1.3 Response Envelope (Modern API)

Modern JSON endpoints return their results in:

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

In the event of failure, success is false, value is null and errorMessage contains the reason.

1.4 Response Style (Legacy API)

The Legacy / *.jsp Endpoints return plain text:

• true — Request succeeded.
• false|<ERROR_CODE> — Request failed; the code indicates the cause.

1.5 Rate Limiting

Several endpoints are rate-limited per session, per JWT, or globally. Limits are listed in the endpoint reference where applicable. When a limit is exceeded, the server responds with an HTTP 429.

2. Legacy API (JSP)

These are the original public endpoints. They are retained for backward compatibility with deployed mail plugins and third-party scripts. New integrations should use the modern equivalents described in the following chapters; the table below shows which legacy URL redirects to which modern path.

Each legacy endpoint is described in detail below.

2.1 Upload Files — process_upload.jsp

Content-Type: multipart/form-data

Upload one or more files in a single transfer. Forwards to /api/transfer/v1/send-outlook-transfer. Returns plain text: true upon success, false|<ERROR_CODE> on failure.

Parameters

Response

Plain text.

true
false|VIRUS_FOUND

Error codes

• VIRUS_FOUND — A virus was detected in one of the files. The transfer was canceled.
• NO_RECIPIENT_GIVEN — No recipients were specified for the transfer.
• FILETYPE_NOT_ALLOW — File type prohibited by MIME or extension policy.
• PASSWORD_MANDATORY_BUT_NOT_GIVEN — A password is required by policy but is missing.
• CANNOT_SEND_MAIL — FileCap was unable to send the notification email (mail server or relay misconfigured).
• API_KEY_INVALID — The provided APIKey is not valid.
• GENERAL_ERROR — Unknown error; check the FileCap server log for the stack trace. This is often a network or proxy issue.

2.2 Send Invite — invite.jsp

Content-Type: application/x-www-form-urlencoded

Send a FileCap invitation to an external user, asking them to upload files for the person who sent the invitation. Forwards to /api/invite/old. Returns plain text true / false|<ERROR_CODE>.

Parameters

Response

Plain text.

true
false|CANNOT_SEND_MAIL

Error codes

• CANNOT_SEND_MAIL — The mail server was unable to process the invitation email.
• CANNOT_ADD_INVITE_TO_DB — FileCap was unable to save the invite ID.
• UNKNOWN_ERROR — An exception was thrown. Check the server log.

2.3 Mail Plugin Settings — mailPluginSettings.jsp

Content-Type: application/x-www-form-urlencoded

Request the FileCap server settings used by email plugins (Outlook Classic, etc.). Forwards to /api/settings/outlook-windows. Returns the plug-in configuration as XML.

Parameters

Response

XML document containing the maximum file size, allowed file extensions, password policy, verification methods, branding, etc.

2.4 Check File — checkFile.jsp

Content-Type: application/x-www-form-urlencoded

Before uploading, verify whether a single file is permitted by the server policy (file extension and MIME blocklists, sender restrictions). Forwards to /api/validate/file.

Parameters

Response

Plain text true when permitted, false|<ERROR_CODE> when blocked.

2.5 Inspect Transfer — checkTransfer.jsp

Content-Type: application/x-www-form-urlencoded

Inspect a previously created transfer (used by email plugins to check status and contents). Forwards to /api/validate/transfer.

Parameters

Response

Plain text response containing the transfer status and file list.

2.6 Check Domain — domainCheck.jsp

Content-Type: application/x-www-form-urlencoded

Verify whether the sender's domain is permitted to send messages to the recipient's domain (whitelist / IP rules). Forwards to /api/validate/domain.

Parameters

Response

Plain text true / false|<ERROR_CODE>.

3. Transfer

Modern transfer endpoints under /FileCap/api/transfer. The 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 to which the legacy JSP forwards (text response) and is documented for the sake of completeness.

3.1 Send Outlook Transfer (Modern, JSON Response)

Content-Type: multipart/form-data

Modern Outlook plugin upload endpoint. Same form fields as process_upload.jsp; the response is a JSON ApiResult<ApiUploadValue>. Rate-limited per session (SendOutlookTransfer).

Example file metadata value (sent as a single text form field)

[
  { "filename": "report.pdf", "mimetype": "application/pdf", "size": 102400 },
  { "filename": "photo.jpg",  "mimetype": "image/jpeg",      "size": 51200 }
]

Parameters

Response

JSON. Example:

{
  "success": true,
  "value": {
    "transferId": "263478632784632748237513",
    "generatedPassword": "Ax9!kp2Qm"
  },
  "errorMessage": null
}

Notes

• Rate limit: SendOutlookTransfer (per session).

3.2 Send Outlook Transfer (Legacy v1, Text Response)

Content-Type: multipart/form-data

Plain-text version of the upload (returns true / false|<ERROR_CODE>). This is the endpoint that process_upload.jsp forwards to. Use it when the calling client requires the legacy text response format.

Parameters

Response

Plain text.

true
false|API_KEY_INVALID

3.3 Validate Upload (Pre-Flight)

Content-Type: application/json

Validate the metadata of an upload before sending any data. Checks server quota, allowed file extensions and MIME types, maximum size, etc. The aliased path /transfer/validateUpload works just as well.

Request body

{
  "lang": "NL",
  "fileMetadataList": [
    {
      "fileName": "report.pdf",
      "fileSize": 102400,
      "mimeType": "application/pdf"
    }
  ]
}

Response

ApiResult<Void> — only success and errorMessage are populated.

3.4 Validate Files

Content-Type: application/json

Per-file validation. Returns one entry per file indicating whether it is allowed and, if not, which rule was violated.

Request body

{
  "lang": "NL",
  "fileMetadataList": [
    { "fileName": "clean.pdf",     "fileSize": 1024, "mimeType": "application/pdf" },
    { "fileName": "forbidden.exe", "fileSize": 2048, "mimeType": "application/x-msdownload" }
  ]
}

Response

ApiResult<ValidateFilesResultModel>.

3.5 Validate Recipient

Content-Type: application/json

Validate the sender/recipient combination against domain whitelists, IP allowlists, and the emailMaySend / emailMayReceive rules.

Request body

{
  "senderEmailAddress": "kees@example.com",
  "recipientEmailAddress": "piet@receiver.com"
}

Response

ApiResult<Void>.

Error codes

• VALIDATION_ERROR_DOMAIN_INVALID — The recipient or sender domain is not allowed.
• VALIDATION_ERROR_EMAIL_ADDRESS — One of the email addresses is invalid.

3.6 Send a reply

Content-Type: multipart/form-data

Send a secure reply to an existing transfer. The original transfer is identified by its transfer ID. Rate-limited (SendReply). Same multipart parser as in section 3.1, so when file parts are attached, the fileMetadata The field MUST appear before them.

Parameters

Response

ApiResult<SentTransferInfo>.

3.7 Check Connection

Content-Type: application/json

Lightweight liveness probe. Always returns ApiResult.success("connected") when the FileCap portal is accessible.

Response

Always returns:

{ "success": true, "value": "connected", "errorMessage": null }

4. Invite

Endpoints for sending FileCap invites. The entire controller is rate-limited to 10 requests per minute.

4.1 Send Invite (Modern JSON)

Content-Type: application/json

A modern JSON version of the legacy format invite.jsp flow. Accepts a list of invitees in a single call.

Request body

{
  "apiKey": "HKADASD68768768ASDASDASDAD",
  "deviceApiKey": "",
  "sender": {
    "emailAddress": "kees@example.com",
    "name": "Kees Janssen"
  },
  "invitees": [
    "piet@company.com",
    "jan@partner.com"
  ],
  "message": "Please upload the requested documents."
}

Response

ApiResult<Void>.

Notes

• Rate limit: 10 requests per minute (InviteService).

4.2 Send Invite (legacy form, /invite/old)

Content-Type: application/x-www-form-urlencoded

Direct call to the endpoint that invite.jsp forwards to. Returns plain text true / false|<ERROR_CODE>.

Parameters

Response

Plain text true / false|<ERROR_CODE>.

4.3 Generate Invite ID

Content-Type: application/json

Pre-generate the invite ID used in the id field of the legacy invite call (the value starting with iiiii). Alias path: /invite/generateInviteId.

Request body

{
  "apiKey": "HKADASD68768768ASDASDASDAD",
  "deviceApiKey": "",
  "sender": {
    "emailAddress": "kees@example.com"
  }
}

Response

ApiResult<String> — the generated invite ID.

5. Settings

Server settings used by clients and plugins: password policy, recipient verification options, branding, plugin settings.

5.1 Password Rules (Detailed)

Content-Type: application/json

Detailed description of the password requirements.

Request body

{
  "apiKey": "HKADASD68768768ASDASDASDAD",
  "lang": "NL"
}

Response

ApiResult<PasswordRules>:

{
  "success": true,
  "value": {
    "enabled": true,
    "title": "Password requirements",
    "rules": [
      { "description": "At least 8 characters", "requirement": ".{8,}" },
      { "description": "At least one digit", "requirement": "(?=.*\\d)" }
    ]
  }
}

Error codes

• UNEXPECTED_ERROR — Internal server error; check the server log.

5.2 Password Rules (GET, public)

Public, unauthenticated GET version. Returns the same ApiResult<PasswordRules> body.

Parameters

5.3 Password Policy (Short)

Content-Type: application/json

Brief summary of the password requirements: minimum length, character classes, expiration, reuse.

Request body

{
  "apiKey": "HKADASD68768768ASDASDASDAD"
}

Response

ApiResult<PasswordPolicy>.

Error codes

• UNEXPECTED_ERROR — Internal server error; check the server log.

5.4 Mail Plugin Settings (XML)

Content-Type: application/x-www-form-urlencoded

Endpoint that mailPluginSettings.jsp forwards to. Returns the plug-in configuration as XML.

Parameters

Response

XML document. Also available as a JSON version at the same path (POST application/json) which returns an HTTP 202 response + ApiResult<OutlookClassicSettings>, or an HTTP 401 error when authentication fails.

5.5 Recipient Verification Options

Content-Type: application/json

Lists the verification methods that can be applied to a transfer (e.g., NONE, EMAIL_ACCESS_CODE, SMS, PASSWORD) and which ones are required under current policy.

Request body

{ "apiKey": "HKADASD68768768ASDASDASDAD" }

Response

ApiResult<RecipientVerificationOptions>.

Error codes

• UNEXPECTED_ERROR — Internal server error; check the server log.

5.6 App Settings

Content-Type: application/json

Generic settings bundle for client apps: enabled features, maximum upload size, branding, supported languages, etc.

Request body

{
  "apiKey": "HKADASD68768768ASDASDASDAD",
  "lang": "NL"
}

Response

ApiResult<AppSettings>.

Error codes

• UNEXPECTED_ERROR — Internal server error; check the server log.

5.7 Web Portal Settings

Returns ApiResult<WebPortalSettings> for the web portal (theme, locale options, feature flags). Allowed for portal types MAIN, SUB, and FREE.

Parameters

5.8 Is a shared access code available?

Content-Type: application/json

Returns a raw boolean (true / false) — not wrapped in ApiResult — indicating whether a shared access code has been configured for the given transfer.

Request body

{ "transferId": "263478632784632748237513" }

Response

Raw Boolean: true or false. Returns false in the event of any internal error.

6. Validation

Lightweight validators that mail plugins call before composing or sending a message. All endpoints under /api/validate return plain text (true / false|<ERROR_CODE>).

6.1 Check File (Form)

Content-Type: application/x-www-form-urlencoded

Validate a single file by name and MIME type against the policy engine. Path that checkFile.jsp forwards to.

Parameters

Response

Plain text true / false|<ERROR_CODE>.

6.2 Check Transfer

Content-Type: application/x-www-form-urlencoded

Path that checkTransfer.jsp forwards to.

Parameters

Response

Plain text true / false|<ERROR_CODE>.

6.3 Check Domain

Content-Type: application/x-www-form-urlencoded

Path that domainCheck.jsp forwards to. Validates the sender's domain against the recipient's domain.

Parameters

Response

Plain text true / false|<ERROR_CODE>.

6.4 The sender may send

Content-Type: text/plain

Returns a raw boolean for the question "Is this sender allowed to send via FileCap?". The body is the plain email address as text/plain.

Response

Raw Boolean: true / false.

7. Business Rules (DLP)

Endpoints for the policy / DLP engine. Both endpoints require either DEVICE or API_KEY authentication and are rate-limited to 60 requests per minute.

7.1 Scan Attachment

Content-Type: multipart/form-data

Run a DLP/business-rules scan on a single attachment.

Parameters

Response

ApiResult<BusinessRulesScanResult> along with the scan results and any policy violations.

Notes

• Rate limit: 60 requests per minute (ScanAttachment).

7.2 Scan text

Content-Type: application/json

Run a DLP scan on arbitrary text.

Request body

{
  "text": "Hello, this is the message body that needs to be scanned for sensitive data."
}

Response

ApiResult<BusinessRulesScanResult>.

Notes

• Rate limit: 60 requests per minute (ScanText).

8. Block Transfer

Sender-facing endpoints to inspect and revoke (block) a transfer that has already been sent. When a transfer is created, FileCap stores a hashed blockPassword along with the transfer and emails, the SENDER receives a notification containing a block link in the following format:

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

The JSP sanitizes the parameters and redirects to the portal's "block" page, which loads transfer metadata via GET /api/block/info and — upon confirmation — calls POST /api/block to actually block the transfer. The blockId Here's the secret: anyone with the transferId, blockId, and sender's email address can block the transfer; no API key or session is required. Every validation failure (incorrect blockId, incorrect sender, unknown transferId) deliberately returns the same generic error PORTAL_BLOCK_TRANSFER_NOT_FOUND so the caller cannot tell which field was incorrect.

8.1 Get block information

Return the metadata that the FileCap web UI displays on the block confirmation page: the TO recipients of the transfer, the file names, and a flag indicating whether the message body was encrypted. The call is read-only—it does not modify the transfer, send any email, or write to the audit log.

Validation order (each failure collapses to PORTAL_BLOCK_TRANSFER_NOT_FOUND (unless otherwise noted):

1. All three parameters must be non-blank;
2. the transfer must exist;
3. SHA hash of blockId must match the stored blockPassword;
4. emailAddress must be a known sender of the transfer;
5. The transfer must not be DISABLED — otherwise PORTAL_DOWNLOAD_TRANSFER_EXPIRED;
6. The transfer must not already be BLOCKED — otherwise PORTAL_BLOCK_TRANSFER_ALREADY_BLOCKED.

Parameters

Response

ApiResult<TransferBlockInfo> with three fields: recipients (array of email addresses of the TO recipients), files (a set of filenames within the transfer, without a path) and hasEncryptedMessage (true (when the message body was encrypted at the time of upload). Example success body:

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

8.2 Block Transfer

Content-Type: application/json

Mark the transfer as blocked. After a successful call:

1. the transfer status is set to BLOCKED — subsequent download attempts (via the web portal or API) are rejected;
2. an NTA audit-log entry is written ("user <sender> blocked transfer with id <transferId>");
3. An email notification stating "message withdrawn" is sent to all TO and CC recipients of the original transfer.

Parameters (request body fields)

Request body

{
  "transferId": "263478632784632748237513",
  "blockId": "BLK-1234",
  "emailAddress": "kees@example.com"
}

Response

ApiResult<Void> — only success and errorMessage are populated. Possible error messages:

• PORTAL_BLOCK_TRANSFER_NOT_FOUND — a generic catch-all for missing parameters, an unknown transfer, an incorrect block ID, an incorrect sender email address, or any unexpected exception — deliberately ambiguous so that the server does not reveal which field was incorrect.
• PORTAL_DOWNLOAD_TRANSFER_EXPIRED — the transfer has already expired (status DISABLED).
• PORTAL_BLOCK_TRANSFER_ALREADY_BLOCKED — The transfer had been blocked previously.
• PORTAL_BLOCK_TRANSFER_ERROR — The database update failed.

9. Device Registration

Endpoints for registering an external device (a third-party system) with the FileCap server so that it can call the API using its own per-device API key. The process is as follows: register → the server sends a verification code via email → verify → the caller receives a JWT / device token.

9.1 Register Device

Content-Type: application/json

Initiate device registration. The server sends a verification code via email to emailAddress.

Request body

{
  "emailAddress": "kees@example.com",
  "apiKey": "HKADASD68768768ASDASDASDAD",
  "deviceName": "My integration server",
  "lang": "NL"
}

Response

ApiResult<Void>.

Notes

• Rate-limited (RegisterDevice).

9.2 Verify Device

Content-Type: application/json

Exchange the verification code sent by email for a JWT or device token.

Request body

{
  "email": "kees@example.com",
  "verificationCode": "123456"
}

Response

ApiResult<String> — the issued token.

Notes

• Rate-limited (VerifyDevice).