Operate Endpoint

A single endpoint that handles all client and loan operations. The status field determines which operation is performed, and the data field contains the operation-specific payload.

Each request is processed asynchronously - the endpoint returns immediately with a tracking_id that can be used to poll for the result.

Endpoint

POST /fineract/operate

Headers

Key	Value
Content-Type	application/json
X-Internal-Token	Your internal orchestration token

Payload Structure

{
    "status": "<OPERATION_STATUS>",
    "data": { ... }
}

Supported Operations

Status	Operation	Description
CLIENT_CREATE	Create Client	Creates a new client in Fineract
CLIENT_UPDATE	Update Client	Updates an existing client by LOS ID
LOAN_CREATE	Create Loan	Creates a new loan in Fineract
LOAN_UPDATE	Update Loan	Updates an existing loan by LOS ID
LOAN_APPROVE	Approve Loan	Approves a loan by LOS loan ID
LOAN_DISBURSE	Disburse Loan	Disburses a loan by LOS loan ID
LOAN_DELETE	Delete Loan	Deletes a loan by LOS loan ID

---

CLIENT_CREATE

Creates a new client in Fineract.

{
  "status": "CLIENT_CREATE",
  "data": {
    "firstname": "Jayesh",
    "lastname": "Badgujar",
    "externalId": "INC-1001",
    "mobileNo": "9966999999",
    "emailAddress": "jayesh@example.com",
    "activationDate": "01 January 2026"
  }
}

Field	Type	Required	Description
firstname	string	Yes	Client first name
lastname	string	Yes	Client last name
externalId	string	Yes	Unique LOS client ID
mobileNo	string	No	Mobile number
emailAddress	string	No	Email address
activationDate	string	Yes	Format: dd MMMM yyyy

---

CLIENT_UPDATE

Updates an existing client by their LOS external ID.

{
  "status": "CLIENT_UPDATE",
  "data": {
    "externalId": "INC-1001",
    "activationDate": "10 January 2026",
    "firstname": "Jayesh",
    "lastname": "Badgu",
    "mobileNo": "9966999999",
    "emailAddress": "jayesh@ex.com"
  }
}

Field	Type	Required	Description
externalId	string	Yes	LOS client ID to update
activationDate	string	No	Updated activation date
firstname	string	No	Updated first name
lastname	string	No	Updated last name
mobileNo	string	No	Updated mobile number
emailAddress	string	No	Updated email address

---

LOAN_CREATE

Creates a new loan in Fineract, linked to an existing client.

{
  "status": "LOAN_CREATE",
  "data": {
    "lenderConfig": "UGRO",
    "externalId": "LOAN-123",
    "principal": 100000,
    "submittedOnDate": "11 January 2026",
    "loanTermFrequency": 12,
    "loanTermFrequencyType": "months",
    "numberOfRepayments": 12,
    "interestRatePerPeriod": 8,
    "clientId": "INC-1001"
  }
}

Field	Type	Required	Description
lenderConfig	string	Yes	Loan product name (e.g., UGRO, DMI, ARTHMATE)
externalId	string	Yes	LOS loan ID
principal	float	Yes	Loan amount
submittedOnDate	string	Yes	Submission date (dd MMMM yyyy)
loanTermFrequency	int	Yes	Loan term length
loanTermFrequencyType	string	No	days, weeks, months (default), or years
numberOfRepayments	int	Yes	Number of EMI installments
interestRatePerPeriod	float	Yes	Interest rate per period
clientId	string	Yes	LOS client ID (from CLIENT_CREATE)

Supported Lender Configs

Value	Lender
LIQUILOANS	Liquiloans
UGRO	Ugro Capital
DMI	DMI Finance
ARTHMATE	Arthmate
SHIVALIK	Shivalik Small Finance Bank
VIVRITI	Vivriti Capital
GB	Gromor / Growth Bharat
IKF	IKF Finance
LENDINGKART	Lendingkart

---

LOAN_UPDATE

Updates an existing loan (only before approval).

{
  "status": "LOAN_UPDATE",
  "data": {
    "externalId": "LOAN-123",
    "principal": 200000,
    "submittedOnDate": "11 January 2026",
    "loanTermFrequency": 24,
    "loanTermFrequencyType": "months",
    "numberOfRepayments": 24,
    "interestRatePerPeriod": 8.3
  }
}

Field	Type	Required	Description
externalId	string	Yes	LOS loan ID to update
principal	float	No	Updated loan amount
submittedOnDate	string	No	Updated submission date
loanTermFrequency	int	No	Updated loan term
loanTermFrequencyType	string	No	days, weeks, months, or years
numberOfRepayments	int	No	Updated repayment count
interestRatePerPeriod	float	No	Updated interest rate

---

LOAN_APPROVE

Approves a loan by its LOS loan ID.

{
  "status": "LOAN_APPROVE",
  "data": {
    "external_loan_id": "LOAN-123",
    "approvedOnDate": "11 January 2026"
  }
}

Field	Type	Required	Description
external_loan_id	string	Yes	LOS loan ID to approve
approvedOnDate	string	Yes	Approval date (dd MMMM yyyy)

---

LOAN_DISBURSE

Disburses a loan by its LOS loan ID.

{
  "status": "LOAN_DISBURSE",
  "data": {
    "external_loan_id": "LOAN-123",
    "actualDisbursementDate": "11 January 2026",
    "transactionAmount": 200000,
    "utr_payment_id": "UTR-20260111-001",
    "note": "Disbursement for LOAN-123"
  }
}

Field	Type	Required	Description
external_loan_id	string	Yes	LOS loan ID to disburse
actualDisbursementDate	string	Yes	Disbursement date (dd MMMM yyyy)
transactionAmount	float	No	Amount to disburse (defaults to full principal)
utr_payment_id	string	No	UTR/payment ID for tracking
note	string	No	Disbursement note

---

LOAN_DELETE

Deletes a loan by its LOS loan ID.

{
  "status": "LOAN_DELETE",
  "data": {
    "external_loan_id": "LOAN-123"
  }
}

Field	Type	Required	Description
external_loan_id	string	Yes	LOS loan ID to delete

WARNING

Only loans in "Submitted and awaiting approval" status can be deleted. Approved or disbursed loans cannot be deleted.

---

Recommended Workflow

To process a full loan lifecycle, call /fineract/operate sequentially, polling the tracking endpoint between each step:

1. CLIENT_CREATE → poll until status != "processing" → confirm "success"
2. LOAN_CREATE → poll → confirm
3. LOAN_APPROVE → poll → confirm
4. LOAN_DISBURSE → poll → confirm

To delete a loan (only if not yet approved):

5. LOAN_DELETE → poll → confirm