Overview

The Comments API enables adding and retrieving comments/notes for various banking entities. Comments provide an audit trail of interactions, decisions, and observations related to clients, loans, deposits, and insurance policies.

Base Endpoint

POST /api/core/cmd

Available Commands

Commands

• Add Comment - Add a comment to any entity (Client, Loan, Deposit, Policy)

Queries

• Retrieve Comments List - Get paginated list of all comments with filters
• Retrieve Client Comments - Get all comments for a specific client
• Retrieve Loan Comments - Get all comments for a specific loan
• Retrieve Deposit Comments - Get all comments for a specific deposit
• Retrieve Policy Comments - Get all comments for an insurance policy

Key Features

• Multi-Entity Support: Add comments to clients, loans, deposits, and insurance policies
• Unified API: Single command to add comments to any entity type
• Flexible Identification: Use database IDs or encoded keys/account numbers
• Audit Trail: Automatic capture of user identity and timestamp
• Search & Filter: Find comments by entity, date range, or text search
• Pagination: Efficient retrieval of large comment sets
• Export: Excel export for reporting and analysis

Supported Entities

Entity Type	Description	Use Cases
Client	Customer/Client comments	Service interactions, KYC notes, relationship management
Loan	Loan account comments	Approval decisions, disbursement notes, collection remarks
Deposit	Deposit account comments	Account status changes, renewal decisions, withdrawal requests
Policy	Insurance policy comments	Premium payments, beneficiary changes, claim notes

Comment Best Practices

Good Comment Examples

Client Comment:

"Customer called regarding unauthorized transaction on 2025-12-20. Case escalated to fraud department. Ref: FRAUD-2025-001. Customer provided transaction details and filed dispute form."

Loan Comment:

"Credit committee approved loan of ₦5,000,000 at 12% interest for 24 months. Collateral: Property at 123 Main St valued at ₦8,000,000. DTI ratio: 35%. Credit score: 750."

Deposit Comment:

"Fixed deposit matured on 2025-12-24. Principal ₦1,000,000 + Interest ₦120,000 = Total ₦1,120,000. Customer opted for renewal at 11% for 12 months."

Policy Comment:

"Premium payment of ₦50,000 received via bank transfer on 2025-12-24. Policy now active until 2026-12-24. Beneficiary updated to spouse per customer request."

Poor Comment Examples

❌ "Called customer"
❌ "Approved"
❌ "Updated"
❌ "See attached"

Authentication

All Comments APIs require authentication via JWT Bearer token:

Authorization: Bearer <your-jwt-token>

Common Patterns

Pagination

All list queries support pagination:

{
  "pageNumber": 1,
  "pageSize": 50
}

Date Range Filtering

Filter comments by date range:

{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31"
}

Text Search

Search comments by text:

{
  "searchText": "approval"
}

Excel Export

Export comments to Excel:

{
  "isExport": true
}

Security & Compliance

Access Control

• Users can only view comments for entities they have permission to access
• Comment creation is logged with user identity
• All operations require valid JWT authentication

Audit Trail

Every comment includes:

• UserName: Who created the comment
• UserEncodedKey: User identifier
• TimeStamp: When comment was created

Data Privacy

• Comments may contain personal or sensitive information
• Ensure compliance with data protection regulations
• Regular audits recommended for PII/sensitive data

Response Structure

All comment APIs return a consistent response structure:

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Operation successful",
  "Data": {
    // Command-specific response data
  }
}

Error Handling

Common Status Codes

Code	Meaning
00	Success
96	Validation error / Invalid request
99	System error

Error Response Example

{
  "IsSuccessful": false,
  "StatusCode": "96",
  "Message": "Entity type is required.",
  "Data": null
}

Next Steps

Explore the individual command and query documentation:

1. Add Comment - Learn how to create comments
2. Retrieve Comments List - Query comments with filters
3. Entity-Specific Queries - Get comments for specific entities