Skip to main content
PUT
/
api
/
loans
/
:id
/
status
curl -X PUT "https://api.example.com/api/loans/cm4newloan1/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED",
    "notes": "Loan approved after verification of documents"
  }'

{
  "success": true,
  "message": "Loan status updated successfully",
  "data": {
    "id": "cm4newloan1",
    "loanNumber": "LN00000042",
    "unionMemberId": "cm4xyz789",
    "unionId": "cm4union1",
    "principalAmount": 50000.00,
    "status": "APPROVED",
    "processingFeeCollected": true,
    "notes": "Business expansion loan\n\nLoan approved after verification of documents",
    "unionMember": {
      "id": "cm4xyz789",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    },
    "union": {
      "id": "cm4union1",
      "name": "Lagos Central Union"
    },
    "assignedOfficer": {
      "id": "cm4officer1",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com"
    },
    "updatedAt": "2026-03-11T16:20:00.000Z"
  }
}

​
Authentication

Requires authentication. Available to: ADMIN, SUPERVISOR (Branch Manager role) Note: CREDIT_OFFICER role cannot change loan status.

​
Path Parameters

​
id
string
required
Loan ID

​
Request Body

​
status
string
required
New loan status. Available values:
  • DRAFT - Loan is being drafted
  • PENDING_APPROVAL - Awaiting approval
  • APPROVED - Approved (ready for disbursement, processing fee marked as collected)
  • ACTIVE - Currently active and being repaid
  • COMPLETED - Fully repaid and closed
  • DEFAULTED - In default status
  • WRITTEN_OFF - Written off
  • CANCELED - Canceled loan
​
notes
string
Additional notes about the status change. These notes are appended to existing loan notes.

​
Response

​
success
boolean
Indicates if the request was successful
​
message
string
Response message (“Loan status updated successfully”)
​
data
object
Updated loan object including related data

​
Status Transitions

Only specific status transitions are allowed. Here are the valid transitions:

​
From DRAFT

  • → PENDING_APPROVAL - Submit for approval
  • → APPROVED - Direct approval (typically by ADMIN)
  • → CANCELED - Cancel the draft

​
From PENDING_APPROVAL

  • → APPROVED - Approve the loan
  • → CANCELED - Reject/cancel the loan

​
From APPROVED

  • → ACTIVE - Disburse the loan (use the separate /disburse endpoint instead)
  • → CANCELED - Cancel before disbursement

​
From ACTIVE

  • → COMPLETED - Mark as fully repaid
  • → DEFAULTED - Mark as in default
  • → WRITTEN_OFF - Write off the loan

​
From DEFAULTED

  • → ACTIVE - Restore to active status
  • → WRITTEN_OFF - Write off the defaulted loan

​
From COMPLETED

No transitions allowed (terminal state)

​
From WRITTEN_OFF

No transitions allowed (terminal state)

​
From CANCELED

  • → PENDING_APPROVAL - Resubmit for approval

​
Automatic Actions

​
When Status Changes to APPROVED

  • processingFeeCollected is automatically set to true

​
When Status Changes to COMPLETED, WRITTEN_OFF, or CANCELED

  • closedAt timestamp is automatically set to current date/time

​
Email Notifications

When loan status is updated, automatic email notifications are sent to:
  1. Union member (loan recipient) - if email is available
  2. Assigned credit officer - if assigned and email is available

​
Permission Model

  • ADMIN: Can update status of any loan (subject to valid transitions)
  • SUPERVISOR/Branch Manager: Can update status of loans in their scope
  • CREDIT_OFFICER: Cannot change loan status (403 error)
curl -X PUT "https://api.example.com/api/loans/cm4newloan1/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED",
    "notes": "Loan approved after verification of documents"
  }'

{
  "success": true,
  "message": "Loan status updated successfully",
  "data": {
    "id": "cm4newloan1",
    "loanNumber": "LN00000042",
    "unionMemberId": "cm4xyz789",
    "unionId": "cm4union1",
    "principalAmount": 50000.00,
    "status": "APPROVED",
    "processingFeeCollected": true,
    "notes": "Business expansion loan\n\nLoan approved after verification of documents",
    "unionMember": {
      "id": "cm4xyz789",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    },
    "union": {
      "id": "cm4union1",
      "name": "Lagos Central Union"
    },
    "assignedOfficer": {
      "id": "cm4officer1",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com"
    },
    "updatedAt": "2026-03-11T16:20:00.000Z"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us