Retrieve Loan By ID

Overview

Retrieves detailed information about a specific loan account by its ID.

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": "RetrieveLoanByIdQuery",
  "data": {
    "id": 12345
  }
}

Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "RetrieveLoanByIdQuery"
data	object	Yes	Query data
↳ id	integer	Yes	Loan account ID

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan retrieved successfully",
  "data": {
    "loanId": "LA-2024-00001",
    "loanAccountNumber": "3001234567890",
    "customerId": "CUST-12345",
    "customerName": "John Doe",
    "loanProductId": "PROD-PERSONAL-001",
    "loanProductName": "Personal Loan",
    "loanAmount": 50000.00,
    "outstandingPrincipal": 42000.00,
    "outstandingInterest": 3000.00,
    "totalOutstanding": 45000.00,
    "interestRate": 12.5,
    "loanTerm": 24,
    "monthlyPayment": 2368.75,
    "status": "Active",
    "disbursementDate": "2024-01-15T00:00:00Z",
    "repaymentStartDate": "2024-02-15T00:00:00Z",
    "maturityDate": "2026-01-15T00:00:00Z",
    "nextPaymentDate": "2024-03-15T00:00:00Z",
    "nextPaymentAmount": 2368.75,
    "disbursementAccountId": "ACC-67890",
    "repaymentAccountId": "ACC-67890",
    "branchId": "BRANCH-001",
    "branchName": "Main Branch",
    "loanOfficerId": "OFFICER-123",
    "loanOfficerName": "Jane Smith",
    "collateral": [
      {
        "collateralId": "COL-001",
        "collateralType": "Property",
        "collateralValue": 75000.00,
        "description": "Residential Property"
      }
    ],
    "guarantors": [
      {
        "guarantorId": "CUST-67890",
        "guarantorName": "Alice Johnson",
        "guaranteeAmount": 25000.00,
        "relationshipToBorrower": "Business Partner"
      }
    ],
    "createdAt": "2024-01-10T14:30:00Z",
    "createdBy": "user@bank.com",
    "lastModifiedAt": "2024-01-15T10:00:00Z",
    "lastModifiedBy": "admin@bank.com"
  }
}

Error Response (404 Not Found)

{
  "success": false,
  "message": "Loan not found",
  "errors": [
    {
      "code": "LOAN_NOT_FOUND",
      "message": "No loan found with the specified ID"
    }
  ]
}

Status Codes

Code	Description
200	Loan retrieved successfully
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Loan not found
500	Internal server error

Code Examples

C# Example

public async Task<LoanDetails> GetLoanByIdAsync(long loanId)
{
    var commandRequest = new
    {
        cmd = "RetrieveLoanByIdQuery",
        data = new { id = loanId }
    };
    
    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<LoanDetails>(responseJson);
}

TypeScript/JavaScript Example

async function getLoanById(loanId: number): Promise<any> {
  const commandRequest = {
    cmd: 'RetrieveLoanByIdQuery',
    data: { id: loanId }
  };
  
  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 retrieval failed: ${response.statusText}`);
  }
  
  return await response.json();
}

Notes

• Internal Implementation: This query internally calls RetrieveLoanListQuery with the ID filter

• Response Structure: Returns complete loan details including guarantors, collateral, and schedules

• Permissions: User must have access to view loans for the specified branch/client } });

  const result = await response.json(); return result.data; }

## Notes

- Returns comprehensive loan information including collateral and guarantors
- Outstanding balance reflects current position after all payments
- Next payment information updated after each payment