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:

# Get the LoanCollateralType code ID
GET /fineract-provider/api/v1/codes?name=LoanCollateralType

# Add a collateral type
POST /fineract-provider/api/v1/codes/{codeId}/codevalues

{ "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):

POST /fineract-provider/api/v1/loans/{loanId}/collaterals
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "collateralTypeId": 2,
  "value": 8500.00,
  "description": "2019 Toyota Hilux, Reg: KDA 123X",
  "locale": "en"
}

Field	Required	Meaning
collateralTypeId	Yes	Code value ID from LoanCollateralType
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:

# 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

GET /fineract-provider/api/v1/loans/{loanId}/collaterals

Or include in the full loan response:

GET /fineract-provider/api/v1/loans/{loanId}?associations=collateral

Updating and deleting collateral

# 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:

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:

PUT /fineract-provider/api/v1/loanproducts/{productId}

{
  "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

POST /fineract-provider/api/v1/loans/{loanId}/guarantors
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "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 freezes the amount in the guarantor's savings account at disbursement and releases it on loan closure.

Adding an external guarantor

POST /fineract-provider/api/v1/loans/{loanId}/guarantors

{
  "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 Relationship. Common values:

GET /fineract-provider/api/v1/codes?name=Relationship

Add values:

{ "name": "Spouse" }
{ "name": "Parent" }
{ "name": "Sibling" }
{ "name": "Employer" }
{ "name": "Business Partner" }
{ "name": "Friend" }

Viewing guarantors on a loan

GET /fineract-provider/api/v1/loans/{loanId}/guarantors

Or in the full loan response:

GET /fineract-provider/api/v1/loans/{loanId}?associations=guarantors

Removing a guarantor

DELETE /fineract-provider/api/v1/loans/{loanId}/guarantors/{guarantorId}

If funds are being held, they are released back to the guarantor's savings account when the guarantor is removed or the loan closes.

---

Guarantee Fund Release on Loan Closure

When a loan with held guarantee funds is closed (fully repaid, written off, or otherwise closed), Fineract automatically releases the frozen amounts back to the guarantor's savings account. No manual action is needed.

If a loan is partially written off but not fully closed, guarantee funds remain held until the loan reaches a terminal state.

---

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 LoanCollateralType code values before onboarding clients
holdGuaranteeFunds: true but guarantor's savings has insufficient balance	Disbursement fails validation	Ensure the guarantor has at least the required amount in their savings before disbursement
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