Skip to main content
GET
/
api
/
loans
curl -X GET "https://api.example.com/api/loans?page=1&limit=20&status=ACTIVE" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "Loans retrieved successfully",
  "data": [
    {
      "id": "cm4abc123",
      "loanNumber": "LN00000001",
      "unionMemberId": "cm4xyz789",
      "unionId": "cm4union1",
      "loanTypeId": "cm4type1",
      "principalAmount": 50000.00,
      "currencyCode": "NGN",
      "termCount": 6,
      "termUnit": "MONTH",
      "startDate": "2026-03-01T00:00:00.000Z",
      "endDate": "2026-09-01T00:00:00.000Z",
      "processingFeeAmount": 1000.00,
      "processingFeeCollected": true,
      "penaltyFeePerDayAmount": 100.00,
      "status": "ACTIVE",
      "createdByUserId": "cm4user1",
      "assignedOfficerId": "cm4officer1",
      "disbursedAt": "2026-03-01T10:30:00.000Z",
      "closedAt": null,
      "notes": "Standard business loan",
      "totalPaid": 25000.00,
      "totalOutstanding": 25000.00,
      "unionMember": {
        "id": "cm4xyz789",
        "code": "UM001",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+2341234567890"
      },
      "union": {
        "id": "cm4union1",
        "name": "Lagos Central Union"
      },
      "loanType": {
        "id": "cm4type1",
        "name": "Business Loan"
      },
      "assignedOfficer": {
        "id": "cm4officer1",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]",
        "role": "CREDIT_OFFICER"
      },
      "createdByUser": {
        "id": "cm4user1",
        "firstName": "Admin",
        "lastName": "User",
        "email": "[email protected]",
        "role": "ADMIN"
      },
      "createdAt": "2026-03-01T09:00:00.000Z",
      "updatedAt": "2026-03-11T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

​
Authentication

Requires authentication. Available to: ADMIN, SUPERVISOR, CREDIT_OFFICER

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"20"
Number of loans per page
​
status
string
Filter loans by status. Available values:
  • DRAFT - Loan is being drafted
  • PENDING_APPROVAL - Awaiting approval
  • APPROVED - Approved and ready for disbursement
  • ACTIVE - Currently active and being repaid
  • COMPLETED - Fully repaid
  • DEFAULTED - In default status
  • WRITTEN_OFF - Written off
  • CANCELED - Canceled loan
​
unionId
string
Filter loans by union ID
​
unionMemberId
string
Filter loans by union member ID
​
search
string
Search by loan number, member first name, last name, or member code

​
Response

​
success
boolean
Indicates if the request was successful
​
message
string
Response message
​
data
array
Array of loan objects
​
id
string
Unique loan identifier
​
loanNumber
string
Human-readable loan number (format: LN00000001)
​
unionMemberId
string
ID of the union member who owns this loan
​
unionId
string
ID of the union this loan belongs to
​
loanTypeId
string
ID of the loan type if specified
​
principalAmount
decimal
Principal loan amount
​
currencyCode
string
default:"NGN"
Currency code for the loan
​
termCount
integer
Number of repayment terms
​
termUnit
string
Unit of the term. Available values:
  • DAY
  • WEEK
  • MONTH
​
startDate
datetime
Loan start date
​
endDate
datetime
Expected loan end date
​
processingFeeAmount
decimal
Processing fee amount
​
processingFeeCollected
boolean
default:"false"
Whether processing fee has been collected
​
penaltyFeePerDayAmount
decimal
Penalty fee charged per day for overdue payments
​
status
string
Current loan status (see status enum above)
​
createdByUserId
string
ID of the user who created this loan
​
assignedOfficerId
string
ID of the credit officer assigned to this loan
​
disbursedAt
datetime
Date and time when loan was disbursed
​
closedAt
datetime
Date and time when loan was closed
​
notes
string
Additional notes about the loan
​
totalPaid
number
Total amount paid towards this loan
​
totalOutstanding
number
Remaining outstanding amount
​
unionMember
object
Union member information
​
union
object
Union information
​
loanType
object
Loan type information if specified
​
assignedOfficer
object
Assigned officer information
​
createdByUser
object
User who created the loan
​
createdAt
datetime
Creation timestamp
​
updatedAt
datetime
Last update timestamp
​
pagination
object
​
page
integer
Current page number
​
limit
integer
Items per page
​
total
integer
Total number of loans
​
totalPages
integer
Total number of pages

​
Permission Model

  • ADMIN: Can view all loans across all unions
  • SUPERVISOR: Can view all loans (supervises credit officers)
  • CREDIT_OFFICER: Can only view loans belonging to unions they manage
curl -X GET "https://api.example.com/api/loans?page=1&limit=20&status=ACTIVE" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "Loans retrieved successfully",
  "data": [
    {
      "id": "cm4abc123",
      "loanNumber": "LN00000001",
      "unionMemberId": "cm4xyz789",
      "unionId": "cm4union1",
      "loanTypeId": "cm4type1",
      "principalAmount": 50000.00,
      "currencyCode": "NGN",
      "termCount": 6,
      "termUnit": "MONTH",
      "startDate": "2026-03-01T00:00:00.000Z",
      "endDate": "2026-09-01T00:00:00.000Z",
      "processingFeeAmount": 1000.00,
      "processingFeeCollected": true,
      "penaltyFeePerDayAmount": 100.00,
      "status": "ACTIVE",
      "createdByUserId": "cm4user1",
      "assignedOfficerId": "cm4officer1",
      "disbursedAt": "2026-03-01T10:30:00.000Z",
      "closedAt": null,
      "notes": "Standard business loan",
      "totalPaid": 25000.00,
      "totalOutstanding": 25000.00,
      "unionMember": {
        "id": "cm4xyz789",
        "code": "UM001",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+2341234567890"
      },
      "union": {
        "id": "cm4union1",
        "name": "Lagos Central Union"
      },
      "loanType": {
        "id": "cm4type1",
        "name": "Business Loan"
      },
      "assignedOfficer": {
        "id": "cm4officer1",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]",
        "role": "CREDIT_OFFICER"
      },
      "createdByUser": {
        "id": "cm4user1",
        "firstName": "Admin",
        "lastName": "User",
        "email": "[email protected]",
        "role": "ADMIN"
      },
      "createdAt": "2026-03-01T09:00:00.000Z",
      "updatedAt": "2026-03-11T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us