Appearance
Collateral & Guarantors
Apache Fineract supports two mechanisms for securing loans beyond the borrower's own creditworthiness: collateral (pledged assets) and guarantors (third-party obligation). Both are tracked at the individual loan account level.
Collateral
Collateral records a physical or financial asset pledged by the borrower against the loan. The collateral record captures the asset type, estimated value, and any description needed for internal tracking.
Setting up collateral types
Collateral types are managed as system code values. Before recording any collateral, create the allowed asset types:
bash
# Get the LoanCollateral code and its ID
GET /fineract-provider/api/v1/codes/name/LoanCollateral
# Add a collateral type
POST /fineract-provider/api/v1/codes/{codeId}/codevaluesjson
{ "name": "Real Estate / Land", "position": 1, "isActive": true }
{ "name": "Motor Vehicle", "position": 2, "isActive": true }
{ "name": "Livestock", "position": 3, "isActive": true }
{ "name": "Fixed Deposit Account", "position": 4, "isActive": true }
{ "name": "Jewellery / Gold", "position": 5, "isActive": true }
{ "name": "Equipment / Machinery", "position": 6, "isActive": true }
{ "name": "Group Guarantee", "position": 7, "isActive": true }See Payment Types & Codes for more on system code management.
Attaching collateral to a loan
Collateral is added to a loan account after the loan is created (but typically before or at disbursement):
bash
POST /fineract-provider/api/v1/loans/{loanId}/collaterals
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/jsonjson
{
"collateralTypeId": 2,
"value": 8500.00,
"description": "2019 Toyota Hilux, Reg: KDA 123X",
"locale": "en"
}| Field | Required | Meaning |
|---|---|---|
collateralTypeId | Yes | Code value ID from LoanCollateral |
value | Yes | Estimated market value of the asset in the loan currency |
description | No | Free-text description (registration number, land title reference, etc.) |
Multiple collateral items
A single loan can have multiple collateral records - useful when a borrower pledges several assets:
bash
# Vehicle
POST /fineract-provider/api/v1/loans/{loanId}/collaterals
{ "collateralTypeId": 2, "value": 8500.00, "description": "2019 Toyota Hilux" }
# Land title
POST /fineract-provider/api/v1/loans/{loanId}/collaterals
{ "collateralTypeId": 1, "value": 25000.00, "description": "Title deed ref: LD-4421" }Viewing collateral on a loan
bash
GET /fineract-provider/api/v1/loans/{loanId}/collateralsOr include in the full loan response:
bash
GET /fineract-provider/api/v1/loans/{loanId}?associations=collateralUpdating and deleting collateral
bash
# Update (e.g., revised valuation)
PUT /fineract-provider/api/v1/loans/{loanId}/collaterals/{collateralId}
{ "value": 7800.00, "description": "2019 Toyota Hilux - revalued", "locale": "en" }
# Delete (if collateral is released before loan closure)
DELETE /fineract-provider/api/v1/loans/{loanId}/collaterals/{collateralId}Loan-to-Value Monitoring
Fineract does not enforce a loan-to-value (LTV) ratio automatically - the collateral value is informational. To monitor LTV in your portfolio, compare outstanding principal against total collateral value:
sql
SELECT
l.id AS loan_id,
l.loan_external_id,
l.principal_outstanding_derived AS outstanding,
SUM(lc.value) AS total_collateral_value,
ROUND(l.principal_outstanding_derived / NULLIF(SUM(lc.value), 0) * 100, 2) AS ltv_percent
FROM m_loan l
LEFT JOIN m_loan_collateral_management lc ON lc.loan_id = l.id
WHERE l.loan_status_id = 300
GROUP BY l.id, l.loan_external_id, l.principal_outstanding_derived
ORDER BY ltv_percent DESC;Guarantors
A guarantor is a third party who pledges to service the loan if the borrower defaults. Guarantors can be:
- Existing clients - another client in the Fineract system
- External guarantors - individuals not in the system, recorded with basic details
Enabling guarantors on a loan product
Guarantor configuration is set at the loan product level:
bash
PUT /fineract-provider/api/v1/loanproducts/{productId}json
{
"holdGuaranteeFunds": true,
"guarantorCount": 1,
"mandatoryGuarantee": 50.0,
"minimumGuaranteeFromOwnFunds": 25.0,
"minimumGuaranteeFromGuarantor": 25.0
}| Field | Meaning |
|---|---|
holdGuaranteeFunds | If true, funds are held (frozen) in the guarantor's savings account |
guarantorCount | Minimum number of guarantors required |
mandatoryGuarantee | Percentage of loan amount that must be guaranteed |
minimumGuaranteeFromOwnFunds | Minimum % that must come from the borrower's own savings |
minimumGuaranteeFromGuarantor | Minimum % that must come from guarantors' savings |
Adding an existing client as guarantor
bash
POST /fineract-provider/api/v1/loans/{loanId}/guarantors
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/jsonjson
{
"clientRelationshipTypeId": 1,
"entityId": 55,
"savingsId": 22,
"amount": 1000.00,
"locale": "en"
}| Field | Meaning |
|---|---|
clientRelationshipTypeId | Code value for the relationship (spouse, parent, employer, etc.) |
entityId | Client ID of the guarantor (must be an existing client) |
savingsId | Savings account ID to hold/freeze guarantee funds |
amount | Amount to hold in the guarantor's savings account |
When holdGuaranteeFunds: true on the product, Fineract places a hold on the amount in the guarantor's savings account when the loan is approved, and releases it as the loan is repaid (see Guarantee Fund Release).
Adding an external guarantor
bash
POST /fineract-provider/api/v1/loans/{loanId}/guarantorsjson
{
"clientRelationshipTypeId": 2,
"firstname": "James",
"lastname": "Mwangi",
"dob": "15 June 1975",
"addressLine1": "123 Main Street",
"city": "Nairobi",
"mobileNumber": "+254712345678",
"housePhoneNumber": "",
"comment": "Employer of the borrower",
"dateFormat": "dd MMMM yyyy",
"locale": "en"
}External guarantors are recorded for reference only - no funds are held since they have no account in the system.
Relationship types
Guarantor relationship types are configured as system code values under GuarantorRelationship. Common values:
bash
GET /fineract-provider/api/v1/codes/name/GuarantorRelationshipAdd values:
json
{ "name": "Spouse" }
{ "name": "Parent" }
{ "name": "Sibling" }
{ "name": "Employer" }
{ "name": "Business Partner" }
{ "name": "Friend" }Viewing guarantors on a loan
bash
GET /fineract-provider/api/v1/loans/{loanId}/guarantorsOr in the full loan response:
bash
GET /fineract-provider/api/v1/loans/{loanId}?associations=guarantorsRemoving a guarantor
bash
DELETE /fineract-provider/api/v1/loans/{loanId}/guarantors/{guarantorId}A guarantor with a funding record (held funds) can only be removed together with that record: pass its id, from guarantorFundingDetails in the guarantor response, as ?guarantorFundingId={id}. On an approved or disbursed loan this releases the held amount back to the guarantor's savings account, and Fineract re-checks the product's guarantee requirements afterwards. Otherwise held funds are released as the loan is repaid (see Guarantee Fund Release).
Guarantee Fund Release
Fineract releases held guarantee funds automatically. Each repayment releases a share of the guarantee in proportion to the principal it repays (guarantors' funds first, then the borrower's own funds). Writing the loan off releases all remaining held funds. No manual action is needed.
Undoing the loan approval reverses the hold.
Common Mistakes
| Mistake | Effect | Fix |
|---|---|---|
| Collateral type code values not set up before loan officers try to record collateral | Empty dropdown, officers cannot select a type | Set up LoanCollateral code values before onboarding clients |
holdGuaranteeFunds: true but guarantor's savings has insufficient balance | Loan approval fails validation | Ensure the guarantor has at least the required amount in their savings before approval |
| External guarantors with missing fields | API 400 error | External guarantors require at minimum firstname, lastname, and clientRelationshipTypeId |
| Deleting a guarantor after disbursement with held funds | Funds released mid-loan | Only remove guarantors when closing or rescheduling the loan |