Overview

The Activities API enables tracking and querying of user activities, system events, and audit trails across the BankLingo platform. It provides comprehensive activity logging for compliance monitoring, security audits, and user behavior analysis.

Base Endpoint

POST /api/core/cmd

Available Commands

Queries

• Get Activities - Retrieve activities with optional entity filtering (Client, Loan, Deposit, User)
• Get Logged-In User Activities - Get activities for the currently authenticated user
• Get Client Activities - Get all activities related to a specific client
• Get Loan Activities - Get all activities related to a specific loan
• Get Deposit Activities - Get all activities related to a specific deposit
• Get User Activities - Get all activities performed by a specific user

Key Features

• Comprehensive Audit Trail: Track all user actions and system events
• Multi-Entity Support: Filter activities by Client, Loan, Deposit, or User
• Flexible Identification: Use database IDs or encoded keys
• Date Range Filtering: Query activities within specific timeframes
• Text Search: Find activities by username or account ID
• Pagination: Efficient retrieval of large activity datasets
• User Context: Automatic user-specific filtering for logged-in users
• Security Monitoring: Track failed operations and suspicious activities

Supported Entity Types

Entity Type	Description	Use Cases
Client	Customer activities	Account openings, KYC updates, profile changes
Loan	Loan account activities	Disbursements, payments, approvals, restructuring
Deposit	Deposit account activities	Account creation, transactions, status changes
User	User-performed activities	Logins, transactions created, approvals given

Activity Information Captured

Each activity record includes:

• User Information: Username, user encoded key
• Action Details: Action performed, description
• Timestamp: When the activity occurred
• Affected Entity: Entity type, ID, and name (if applicable)
• Context: Additional activity-specific information

Common Use Cases

1. User Activity Audit

Track all activities performed by a specific user for compliance:

{
  "Cmd": "GetActivitiesQuery",
  "Data": {
    "entity": "User",
    "encodedKey": "8a80866e7f123456789",
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "pageSize": 100
  }
}

2. Client Interaction History

View complete history of activities related to a client:

{
  "Cmd": "GetActivitiesQuery",
  "Data": {
    "entity": "Client",
    "entityId": "12345",
    "pageSize": 50
  }
}

3. Loan Lifecycle Tracking

Monitor all activities on a loan account:

{
  "Cmd": "GetActivitiesQuery",
  "Data": {
    "entity": "Loan",
    "encodedKey": "8a80866e7f98765",
    "startDate": "2025-01-01",
    "pageSize": 50
  }
}

4. Personal Activity Dashboard

Get logged-in user's own activities:

{
  "Cmd": "GetLoggedInUserActivitiesQuery",
  "Data": {
    "startDate": "2025-12-01",
    "endDate": "2025-12-24",
    "pageSize": 50
  }
}

5. Recent Platform Activities

View recent activities across all entities:

{
  "Cmd": "GetActivitiesQuery",
  "Data": {
    "startDate": "2025-12-23",
    "pageNumber": 1,
    "pageSize": 100
  }
}

Activity Types

Common activity types tracked by the system:

• Login/Logout: User authentication events
• Create: Entity creation (clients, accounts, loans)
• Update: Entity modifications
• Delete: Entity deletions
• Transaction: Financial transactions
• Approval: Workflow approvals
• Rejection: Workflow rejections
• Disbursement: Loan disbursements
• Repayment: Loan payments
• Deposit: Deposit transactions
• Withdrawal: Withdrawal transactions
• Export: Data exports
• Import: Data imports

Authentication

All Activities APIs require authentication via JWT Bearer token:

Authorization: Bearer <your-jwt-token>

The logged-in user's context is automatically captured for all activities.

Common Patterns

Date Range Filtering

Filter activities by date range:

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

Default: If not provided, startDate defaults to 10 years ago, endDate to current date.

Pagination

All activity queries support pagination:

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

Default: Page 1, 50 items per page.

Text Search

Search for activities by username or account ID:

{
  "searchText": "john.doe@example.com"
}

Entity Filtering

Filter by entity type and ID:

{
  "entity": "Loan",
  "entityId": "12345"
}

Supported entities: Client, Loan, Deposit, User

Response Structure

All activity APIs return a consistent response structure:

{
  "Status": "00",
  "Message": "Activities retrieved successfully",
  "Data": {
    "activities": [
      {
        "Id": 1001,
        "CreationDate": "2025-12-24T10:30:00",
        "UserName": "jane.doe@banklingo.com",
        "UserKey": "8a80866e7f123456",
        "Action": "Create",
        "ActivityDescription": "Created new deposit account",
        "AffectedItemType": "DepositAccount",
        "AffectedDepositName": "Savings Account",
        "AffectedDepositEncodedKey": "8a80866e7f987654",
        "AffectedDepositId": "DEP-2025-00123"
      }
    ],
    "totalRows": 150,
    "totalPages": 3,
    "currentPage": 1,
    "pageSize": 50
  }
}

Error Handling

Common Status Codes

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

Error Response Examples

Invalid Entity Type:

{
  "Status": "96",
  "Message": "Invalid entity type: Policy. Valid types: Client, Loan, Deposit, User",
  "Data": null
}

Entity Not Found:

{
  "Status": "96",
  "Message": "Loan with ID 99999 not found",
  "Data": null
}

Missing Authentication:

{
  "Status": "96",
  "Message": "User context not found. Please ensure you are authenticated.",
  "Data": null
}

Security & Compliance

Access Control

• GetLoggedInUserActivitiesQuery: Any authenticated user can view their own activities
• GetActivitiesQuery: Typically restricted to administrators or users with audit permissions
• All activities are logged with user context for accountability

Audit Trail

Activities API provides:

• Immutable Records: Activity logs cannot be modified once created
• Complete History: All user actions are captured
• User Attribution: Every activity is linked to a user
• Timestamp Tracking: Precise timing of all events
• Entity Linkage: Activities are linked to affected entities

Data Privacy

• Activity records may contain personal information
• Comply with data protection regulations (GDPR, NDPR, etc.)
• Implement appropriate access controls
• Regular audits recommended

Performance Considerations

Best Practices

1. Use Date Filters: Always specify date ranges to limit result sets
2. Appropriate Page Size: Use reasonable page sizes (50-100 records)
3. Entity Filtering: Filter by specific entities when possible
4. Avoid Over-Querying: Cache results when appropriate
5. Use Specific Queries: Use entity-specific queries for better performance

Caching

Activities data is cached for 10 seconds to improve performance:

• Subsequent identical queries within 10 seconds return cached results
• Cache key includes all filter parameters
• Automatic cache invalidation after refresh interval

Related APIs

• Comments API - User-added notes and comments
• BPMCore API - Core banking operations
• Process Instances - Workflow process tracking

Next Steps

Explore the individual query documentation:

1. Get Activities - General activity retrieval with filters
2. Get Logged-In User Activities - Personal activity dashboard
3. Entity-Specific Queries - Client, Loan, Deposit, User activities

---

Best Practice: For audit and compliance purposes, regularly export activity logs and store them in secure, long-term storage.