Retrieve Loan List

Overview

Retrieves a paginated list of loan accounts with filtering and sorting options.

Endpoint

POST /api/bpm/cmd

Request Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be application/json
X-Tenant-Id	string	Yes	Tenant identifier

Request Body

{
  "cmd": "RetrieveLoanListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "searchText": "John Doe",
    "status": [1, 2, 3],
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "holderId": 12345,
    "asAcountHolder": true,
    "asGuarantor": false,
    "isExport": false
  }
}

Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "RetrieveLoanListQuery"
data	object	Yes	Query filter data
↳ pageNumber	integer	No	Page number (default: 1)
↳ pageSize	integer	No	Items per page (default: 10, max: 100)
↳ searchText	string	No	Search text for loan account details
↳ id	integer	No	Filter by specific loan account ID
↳ status	array[integer]	No	Filter by loan states (array of state enums)
↳ startDate	string	No	Start date for filtering (ISO 8601 date string)
↳ endDate	string	No	End date for filtering (ISO 8601 date string)
↳ holderId	integer	No	Client/Holder ID (required if asAcountHolder or asGuarantor is true)
↳ asAcountHolder	boolean	No	Filter loans where holder is the account holder
↳ asGuarantor	boolean	No	Filter loans where holder is a guarantor
↳ isExport	boolean	No	Set to true for export format (default: false)

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan list retrieved successfully",
  "data": {
    "loans": [
      {
        "loanId": "LA-2024-00001",
        "loanAccountNumber": "3001234567890",
        "customerId": "CUST-12345",
        "customerName": "John Doe",
        "loanProductId": "PROD-PERSONAL-001",
        "loanProductName": "Personal Loan",
        "loanAmount": 50000.00,
        "outstandingBalance": 45000.00,
        "interestRate": 12.5,
        "loanTerm": 24,
        "status": "Active",
        "disbursementDate": "2024-01-15T00:00:00Z",
        "maturityDate": "2026-01-15T00:00:00Z",
        "branchId": "BRANCH-001",
        "branchName": "Main Branch",
        "loanOfficerId": "OFFICER-123",
        "loanOfficerName": "Jane Smith",
        "createdAt": "2024-01-10T14:30:00Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "pageSize": 20,
      "totalPages": 5,
      "totalRecords": 98
    }
  }
}

Status Codes

Code	Description
200	Loan list retrieved successfully
400	Invalid query parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
500	Internal server error

Code Examples

C# Example

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class LoanService
{
    private readonly HttpClient _httpClient;
    
    public async Task<LoanListResponse> GetLoanListAsync(object queryData)
    {
        var commandRequest = new
        {
            cmd = "RetrieveLoanListQuery",
            data = queryData
        };
        
        var json = JsonSerializer.Serialize(commandRequest);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _httpClient.PostAsync(
            "/api/bpm/cmd", 
            content
        );
        
        response.EnsureSuccessStatusCode();
        
        var responseJson = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<LoanListResponse>(responseJson);
    }
}

// Usage
var queryData = new
{
    pageNumber = 1,
    pageSize = 20,
    searchText = "Business Loan",
    status = new[] { 1, 2 }, // Active and Approved states
    startDate = "2024-01-01",
    endDate = "2024-12-31",
    holderId = 12345,
    asAcountHolder = true,
    isExport = false
};

var result = await loanService.GetLoanListAsync(queryData);
Console.WriteLine($"Found {result.Data.TotalRecords} loans");

TypeScript/JavaScript Example

interface RetrieveLoanListRequest {
  cmd: string;
  data: {
    pageNumber?: number;
    pageSize?: number;
    searchText?: string;
    id?: number;
    status?: number[];
    startDate?: string;
    endDate?: string;
    holderId?: number;
    asAcountHolder?: boolean;
    asGuarantor?: boolean;
    isExport?: boolean;
  };
}

async function getLoanList(queryData: RetrieveLoanListRequest['data']): Promise<any> {
  const commandRequest: RetrieveLoanListRequest = {
    cmd: 'RetrieveLoanListQuery',
    data: queryData
  };
  
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-Id': tenantId
    },
    body: JSON.stringify(commandRequest)
  });
  
  if (!response.ok) {
    throw new Error(`Loan list retrieval failed: ${response.statusText}`);
  }
  
  return await response.json();
}

// Usage
const queryData = {
  pageNumber: 1,
  pageSize: 20,
  searchText: 'Business Loan',
  status: [1, 2], // Active and Approved states
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  holderId: 12345,
  asAcountHolder: true,
  isExport: false
};

const result = await getLoanList(queryData);
console.log('Found loans:', result.data.totalRecords);

Notes

• Pagination: Results are paginated for performance (default: 10 items per page)
• Dynamic Predicate Builder: Additional filters can be added dynamically through the Data object
• Date Filtering: Filters by loan creation date, not disbursement date
• Status Filtering: Use loan state enum values (integers) for filtering
• Holder Filtering: Can filter by account holder or guarantor relationship
• Export Mode: Set isExport to true for full dataset without pagination
• Results ordered by DateCreated descending by default