BPMCore Documents API

The Documents API enables uploading, storing, and retrieving documents attached to various banking entities such as clients, loans, deposits, and insurance policies. Files are stored in MinIO object storage with metadata tracked in the database.

Base Endpoint

POST /api/core/cmd

Commands & Queries

1. Create Document (Upload)

Uploads a document and attaches it to a specific banking entity.

Command Name: CreateDocumentCommand

Request Parameters

Parameter	Type	Required	Description
`entityType`	string	Yes	Entity type: "Client", "Loan", "Deposit", or "Policy"
`entityId`	long	Yes	ID of the entity (clientId, loanId, depositId, or policyId)
`fileName`	string	Yes	Original file name with extension
`fileContentBase64`	string	Yes	Base64-encoded file content
`title`	string	No	Document title
`description`	string	No	Document description
`documentNumber`	string	No	Document number (e.g., ID card number)
`documentType`	integer	No	Document type enum value
`documentTypeDescription`	string	No	Document type description
`issueDate`	string	No	Document issue date (YYYY-MM-DD)
`expiryDate`	string	No	Document expiry date (YYYY-MM-DD)

Document Types (Examples)

Value	Description
1	National ID
2	Passport
3	Driver's License
4	Utility Bill
5	Bank Statement
6	Contract
7	Other

Request Example

{
  "Cmd": "CreateDocumentCommand",
  "Data": {
    "entityType": "Client",
    "clientId": 12345,
    "fileName": "passport.pdf",
    "fileContentBase64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYX...",
    "title": "International Passport",
    "description": "Valid passport for KYC verification",
    "documentNumber": "A12345678",
    "documentType": 2,
    "documentTypeDescription": "Passport",
    "issueDate": "2020-01-15",
    "expiryDate": "2030-01-14"
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Document uploaded successfully.",
  "Data": {
    "Identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "FilePath": "documents/clients/12345/passport_3fa85f64.pdf",
    "FileExtension": ".pdf",
    "OriginalFileName": "passport.pdf",
    "UploadedAt": "2024-01-20T14:30:00",
    "UploadedBy": "admin@banklingo.com",
    "StorageProvider": "MinIO"
  }
}

Validation Rules

Entity Must Exist: The specified entity ID must exist in the system
Valid Base64: File content must be valid base64-encoded string
File Size: Maximum file size limits apply (configured in system settings)
Supported Formats: PDF, PNG, JPG, JPEG, DOC, DOCX, XLS, XLSX typically supported
Unique Document Number: Optional but should be unique if provided

Error Responses

{
  "IsSuccessful": false,
  "StatusCode": "01",
  "Message": "Invalid client ID.",
  "Data": null
}

{
  "IsSuccessful": false,
  "StatusCode": "01",
  "Message": "Invalid file content.",
  "Data": null
}

2. Retrieve Documents List (All Entities)

Retrieves a paginated list of all documents across all entity types.

Command Name: RetrieveDocumentsListQuery

Request Parameters

Parameter	Type	Required	Description
`entityType`	string	No	Filter by entity type: "Client", "Loan", "Deposit", "Policy"
`entityId`	long	No	Filter by specific entity ID
`startDate`	string	No	Filter by upload date start (YYYY-MM-DD)
`endDate`	string	No	Filter by upload date end (YYYY-MM-DD)
`searchText`	string	No	Search in file names, titles, descriptions
`documentType`	integer	No	Filter by document type
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20)
`isExport`	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrieveDocumentsListQuery",
  "Data": {
    "entityType": "Client",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "searchText": "passport",
    "pageNumber": 1,
    "pageSize": 50
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Documents retrieved successfully.",
  "Data": {
    "items": [
      {
        "Id": 789,
        "EntityType": "Client",
        "EntityId": 12345,
        "EntityReference": "CL-000123",
        "FileName": "passport.pdf",
        "FilePath": "documents/clients/12345/passport_3fa85f64.pdf",
        "FileExtension": ".pdf",
        "Title": "International Passport",
        "Description": "Valid passport for KYC verification",
        "DocumentNumber": "A12345678",
        "DocumentType": 2,
        "DocumentTypeDescription": "Passport",
        "IssueDate": "2020-01-15",
        "ExpiryDate": "2030-01-14",
        "UploadedAt": "2024-01-20T14:30:00",
        "UploadedBy": "admin@banklingo.com",
        "FileSize": "245760",
        "IsExpired": false
      }
    ],
    "totalRows": 125,
    "totalPages": 3,
    "pageSize": 50,
    "currentPage": 1
  },
  "HasNext": true,
  "HasPrevious": false
}

3. Retrieve Client Documents

Retrieves all documents for a specific client.

Command Name: RetrieveClientDocumentsListQuery

Request Parameters

Parameter	Type	Required	Description
`clientId`	long	Yes	Client ID
`documentType`	integer	No	Filter by document type
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20)
`isExport`	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrieveClientDocumentsListQuery",
  "Data": {
    "clientId": 12345,
    "pageNumber": 1,
    "pageSize": 20
  }
}

Response Structure

Same structure as RetrieveDocumentsListQuery, filtered to the specified client.

4. Retrieve Loan Documents

Retrieves all documents for a specific loan account.

Command Name: RetrieveLoanDocumentsListQuery

Request Parameters

Parameter	Type	Required	Description
`loanId`	long	Yes	Loan account ID
`documentType`	integer	No	Filter by document type
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20)
`isExport`	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrieveLoanDocumentsListQuery",
  "Data": {
    "loanId": 67890,
    "pageNumber": 1,
    "pageSize": 20
  }
}

Typical Loan Documents

Loan application form
Collateral documents
Property valuations
Guarantor documents
Signed loan agreement
Disbursement authorization

5. Retrieve Deposit Documents

Retrieves all documents for a specific deposit account.

Command Name: RetrieveDepositDocumentsListQuery

Request Parameters

Parameter	Type	Required	Description
`depositId`	long	Yes	Deposit account ID
`documentType`	integer	No	Filter by document type
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20)
`isExport`	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrieveDepositDocumentsListQuery",
  "Data": {
    "depositId": 54321,
    "pageNumber": 1,
    "pageSize": 20
  }
}

Typical Deposit Documents

Account opening form
Signature card
Mandate forms
KYC documents
Fixed deposit certificate

6. Retrieve Policy Documents

Retrieves all documents for a specific insurance policy.

Command Name: RetrievePolicyDocumentsListQuery

Request Parameters

Parameter	Type	Required	Description
`policyId`	long	Yes	Insurance policy ID
`documentType`	integer	No	Filter by document type
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20)
`isExport`	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrievePolicyDocumentsListQuery",
  "Data": {
    "policyId": 99887,
    "pageNumber": 1,
    "pageSize": 20
  }
}

Typical Policy Documents

Policy document
Premium payment receipts
Beneficiary designation forms
Claims documentation
Medical reports (for life insurance)

Storage Architecture

MinIO Object Storage

BankLingo uses MinIO as the primary document storage backend:

Scalability: Handles millions of documents
Redundancy: Configurable replication
Security: Encrypted at rest and in transit
Cost-Effective: S3-compatible object storage

File Organization

Documents are organized by entity type:

documents/
├── clients/
│   ├── {clientId}/
│   │   ├── document1_{guid}.pdf
│   │   └── document2_{guid}.jpg
├── loans/
│   ├── {loanId}/
│   │   └── document_{guid}.pdf
├── deposits/
│   ├── {depositId}/
│   │   └── document_{guid}.pdf
└── policies/
    ├── {policyId}/
        └── document_{guid}.pdf

Metadata Storage

Document metadata is stored in the database:

File path and storage location
Entity associations
Upload timestamps
Document attributes (type, expiry, etc.)
User who uploaded

Common Use Cases

Example 1: Client Onboarding

Upload multiple KYC documents during client registration:

// Upload National ID
{
  "Cmd": "CreateDocumentCommand",
  "Data": {
    "entityType": "Client",
    "clientId": 12345,
    "fileName": "national_id.pdf",
    "fileContentBase64": "...",
    "documentType": 1,
    "documentTypeDescription": "National ID",
    "documentNumber": "NIN-12345678",
    "issueDate": "2015-06-20",
    "expiryDate": "2025-06-19"
  }
}

// Upload Utility Bill
{
  "Cmd": "CreateDocumentCommand",
  "Data": {
    "entityType": "Client",
    "clientId": 12345,
    "fileName": "utility_bill.pdf",
    "fileContentBase64": "...",
    "documentType": 4,
    "documentTypeDescription": "Utility Bill",
    "issueDate": "2024-01-10"
  }
}

Example 2: Loan Collateral Documentation

Attach property documents to a loan application:

{
  "Cmd": "CreateDocumentCommand",
  "Data": {
    "entityType": "Loan",
    "loanId": 67890,
    "fileName": "property_valuation.pdf",
    "fileContentBase64": "...",
    "title": "Property Valuation Report",
    "description": "Independent valuation for collateral property at 123 Main St",
    "documentType": 6,
    "documentTypeDescription": "Valuation Report",
    "issueDate": "2024-01-15"
  }
}

Example 3: Document Retrieval for Audit

Retrieve all expired documents requiring renewal:

{
  "Cmd": "RetrieveDocumentsListQuery",
  "Data": {
    "endDate": "2024-01-20",
    "documentType": 1,
    "isExport": true
  }
}

Example 4: Download Client Documents

Retrieve all documents for a specific client:

{
  "Cmd": "RetrieveClientDocumentsListQuery",
  "Data": {
    "clientId": 12345,
    "isExport": true
  }
}

File Handling

Supported File Types

Category	Extensions	Max Size
Documents	PDF, DOC, DOCX	10 MB
Images	PNG, JPG, JPEG, GIF	5 MB
Spreadsheets	XLS, XLSX, CSV	10 MB
Archives	ZIP, RAR	20 MB

Base64 Encoding

JavaScript example for encoding files:

function encodeFileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => {
      // Remove data URL prefix (data:*/*;base64,)
      const base64 = reader.result.split(',')[1];
      resolve(base64);
    };
    reader.onerror = error => reject(error);
  });
}

// Usage
const file = document.getElementById('fileInput').files[0];
const base64Content = await encodeFileToBase64(file);

Decoding for Download

When retrieving documents, the file path points to MinIO storage. Use the BankLingo file download API:

GET /api/files/download?path={filePath}
Authorization: Bearer <token>

Security Considerations

1. Access Control

Users can only access documents for entities they have permission to view
Role-based access controls apply
Audit trails track all document access

2. Encryption

Files encrypted at rest in MinIO
TLS encryption for data in transit
Secure base64 transmission

3. Virus Scanning

Optional virus scanning on upload
Quarantine of suspicious files
Automatic notification to administrators

4. Document Expiry

System tracks document expiry dates
Automated alerts for expiring documents
Workflow triggers for renewal processes

Best Practices

Standardize File Names: Use clear, consistent naming conventions
Add Descriptions: Include meaningful descriptions for easy identification
Set Expiry Dates: Always set expiry dates for time-sensitive documents
Document Type Consistency: Use standardized document types
Regular Audits: Periodically review and purge obsolete documents
Optimize File Sizes: Compress large files before upload
Batch Operations: Use export functionality for bulk retrieval

Integration Notes

Document Lifecycle

Entity Associations

Documents are tightly coupled with banking entities:

Client Documents: Linked to customer profiles
Loan Documents: Attached to loan accounts
Deposit Documents: Associated with deposit accounts
Policy Documents: Connected to insurance policies

Related APIs:

Documentation Author: Owa Oluwasegun Tunbosun, Senior Platform Engineer

Base Endpoint​

Commands & Queries​

1. Create Document (Upload)​

Request Parameters​

Document Types (Examples)​

Request Example​

Response Structure​

Validation Rules​

Error Responses​

2. Retrieve Documents List (All Entities)​

Request Parameters​

Request Example​

Response Structure​

3. Retrieve Client Documents​

Request Parameters​

Request Example​

Response Structure​

4. Retrieve Loan Documents​

Request Parameters​

Request Example​

Typical Loan Documents​

5. Retrieve Deposit Documents​

Request Parameters​

Request Example​

Typical Deposit Documents​

6. Retrieve Policy Documents​

Request Parameters​

Request Example​

Typical Policy Documents​

Storage Architecture​

MinIO Object Storage​

File Organization​

Metadata Storage​

Common Use Cases​

Example 1: Client Onboarding​

Example 2: Loan Collateral Documentation​

Example 3: Document Retrieval for Audit​

Example 4: Download Client Documents​

File Handling​

Supported File Types​

Base64 Encoding​

Decoding for Download​

Security Considerations​

1. Access Control​

2. Encryption​

3. Virus Scanning​

4. Document Expiry​

Best Practices​

Integration Notes​

Document Lifecycle​

Entity Associations​

Base Endpoint

Commands & Queries

1. Create Document (Upload)

Request Parameters

Document Types (Examples)

Request Example

Response Structure

Validation Rules

Error Responses

2. Retrieve Documents List (All Entities)

Request Parameters

Request Example

Response Structure

3. Retrieve Client Documents

Request Parameters

Request Example

Response Structure

4. Retrieve Loan Documents

Request Parameters

Request Example

Typical Loan Documents

5. Retrieve Deposit Documents

Request Parameters

Request Example

Typical Deposit Documents

6. Retrieve Policy Documents

Request Parameters

Request Example

Typical Policy Documents

Storage Architecture

MinIO Object Storage

File Organization

Metadata Storage

Common Use Cases

Example 1: Client Onboarding

Example 2: Loan Collateral Documentation

Example 3: Document Retrieval for Audit

Example 4: Download Client Documents

File Handling

Supported File Types

Base64 Encoding

Decoding for Download

Security Considerations

1. Access Control

2. Encryption

3. Virus Scanning

4. Document Expiry

Best Practices

Integration Notes

Document Lifecycle

Entity Associations