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 mail 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 out of scope.

The API has grown in 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 forward to a modern REST endpoint; both the JSP and the modern path keep working.
2. Modern API – JSON / multipart endpoints under /FileCap/api/... that return a structured ApiResult<T> envelope. New integrations should target this surface.

1.1 Base URL & context root

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

https://filecap.example.com

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

1.2 Authentication

Most endpoints accept an APIKey in the request body (form field, urlencoded 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 the modern endpoints additionally 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 wrap their result in:

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

On 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 identifies the cause.

1.5 Rate limiting

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

2. Legacy API (JSP)

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

Each legacy endpoint is documented 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 on 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 cancelled.
• NO_RECIPIENT_GIVEN — No recipients were supplied for the transfer.
• FILETYPE_NOT_ALLOW — File type forbidden by MIME or extension policy.
• PASSWORD_MANDATORY_BUT_NOT_GIVEN — A password is required by policy but missing.
• CANNOT_SEND_MAIL — FileCap could not send the notification mail (mailserver / relay misconfigured).
• API_KEY_INVALID — The supplied APIKey is not valid.
• GENERAL_ERROR — Unknown error; check the FileCap server log for the stack trace. Often a network / proxy issue.

2.2 Send invite — invite.jsp

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

Send a FileCap invite to an external user, asking them to upload files for the inviter. 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 mailserver could not process the invite mail.
• CANNOT_ADD_INVITE_TO_DB — FileCap could not persist the invite ID.
• UNKNOWN_ERROR — An exception was raised. 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 mail plugins (Outlook classic etc.). Forwards to /api/settings/outlook-windows. Returns the plug-in configuration as XML.

Parameters

Response

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

2.4 Check file — checkFile.jsp

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

Verify – before uploading – whether a single file is allowed by the server policy (extension and MIME blocklists, sender restrictions). Forwards to /api/validate/file.

Parameters

Response

Plain text true when allowed, 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 mail plugins to check status / contents). Forwards to /api/validate/transfer.

Parameters

Response

Plain text response with the transfer status / file list.

2.6 Check domain — domainCheck.jsp

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

Verify whether the sender domain is allowed to send to the recipient 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 the legacy JSP forwards to (text response) and is documented for 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 fileMetadata 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 variant 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 shape.

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 bytes. Checks server quota, allowed extensions / MIME, max size etc. The aliased path /transfer/validateUpload works 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 allow-lists and the emailMaySend / emailMayReceive rules.

Request body

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

Response

ApiResult<Void>.

Error codes

• VALIDATION_ERROR_DOMAIN_INVALID — Recipient or sender domain is not allowed.
• VALIDATION_ERROR_EMAIL_ADDRESS — One of the e-mail addresses is malformed.

3.6 Send 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 section 3.1, so when file parts are attached the fileMetadata 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 reachable.

Response

Always returns:

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

4. Invite

Endpoints for sending FileCap invites. The whole controller is rate-limited at 10 requests / minute.

4.1 Send invite (modern JSON)

Content-Type: application/json

Modern JSON variant of the legacy 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 / 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). Aliased 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

Short 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 exposed as a JSON variant on the same path (POST application/json) which returns HTTP 202 + ApiResult<OutlookClassicSettings>, or HTTP 401 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 mandatory by 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, max 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 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 on 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 + MIME 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 domain against the recipient domain.

Parameters

Response

Plain text true / false|<ERROR_CODE>.

6.4 Check 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 bare e-mail 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 at 60 requests / minute.

7.1 Scan attachment

Content-Type: multipart/form-data

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

Parameters

Response

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

Notes

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

7.2 Scan text

Content-Type: application/json

Run a DLP scan against 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 / 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 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>

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

8.1 Get block info

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. The call is read-only — it does not modify the transfer, send any mail or write to the audit log.

Validation order (every failure collapses to PORTAL_BLOCK_TRANSFER_NOT_FOUND unless 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 e-mail addresses of the TO recipients), files (set of filenames inside the transfer, no path) and hasEncryptedMessage (true when the message body was encrypted at upload time). 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 (web portal or API) are refused;
2. an NTA audit-log entry is written ("user <sender> blocked transfer with id <transferId>");
3. a "message withdrawn" notification mail 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 — generic catch-all for missing parameters, unknown transfer, wrong blockId, wrong sender e-mail or any unexpected exception — deliberately ambiguous so the server does not leak which field was wrong.
• PORTAL_DOWNLOAD_TRANSFER_EXPIRED — the transfer has already expired (status DISABLED).
• PORTAL_BLOCK_TRANSFER_ALREADY_BLOCKED — the transfer was blocked previously.
• PORTAL_BLOCK_TRANSFER_ERROR — the database update failed.

9. Device registration

Endpoints for registering an external device (a 3rd party system) with the FileCap server so it can call the API with its own per-device API key. The flow is: register → the server sends a verification code by mail → verify → caller receives a JWT / device token.

9.1 Register device

Content-Type: application/json

Initiate device registration. The server e-mails a verification code 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 e-mailed verification code for a JWT / device token.

Request body

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

Response

ApiResult<String> — the issued token.

Notes

• Rate-limited (VerifyDevice).