API – Add Collateral to a Loan
Updated 2 weeks ago
General
This article assumes that you have an existing loan. If not, see Creating a Loan with the API.
LoanPro's latest release includes a breaking change in the use of collateral through the API. Now multiple items of collateral can be linked to a single loan. This necessitated a change in the create payload and response structure.
You can add collateral to a loan either in the UI or through the API, which this article explains. Multiple items of collateral can be added to a loan. To add collateral to a loan, you will need to send a PUT request to the URL of the desired loan. For example, to add a vehicle to a loan with ID 515, the URL would be this:
POST https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans(515).
If you don't know the loan's ID, see our article on Finding Loan and Customer IDs.
Please note that the example listed below is for an automobile loan, but other types of collateral are available on the Collateral Collections article.
Request Body
With the latest update, we have a new payload that specifies a position ID for each collateral item, which lets you add up to 50 collateral items in the same call.
Alternatively, you can use the old payload that didn't include the "positionId" value. To keep things backwards compatible, we've left that payload as a usable workaround.
Multiple Collateral Items
You can add multiple items of collateral with a single call by including a position ID for each one. The JSON payload will look something like this:
{
"Collateral": {
"results": [
{
"loanId": "515",
"a": "2017",
"b": "Suzuki",
"c": "VS750GLP",
"d": "Base",
"additional": "Information",
"collateralType": "collateral.type.car",
"vin": "JS1VR51A5H2151359",
"distance": "25000",
"bookValue": "2408.59",
"color": "White",
"gpsStatus": "collateral.gpsstatus.notinstalled",
"gpsCode": "NONE",
"licensePlate": "License Plate Number",
"gap": "1125.25",
"warranty": "1254",
"positionId": 1
},
{
"loanId": "515",
"a": "2020",
"b": "Honda",
"c": "Accord",
"d": "LE",
"additional": "Information",
"collateralType": "collateral.type.car",
"vin": "JS1VR51A5H2151359",
"distance": "13000",
"bookValue": "24708.59",
"color": "Blue",
"gpsStatus": "collateral.gpsstatus.notinstalled",
"gpsCode": "NONE",
"licensePlate": "License Plate Number",
"gap": "0",
"warranty": "0",
"positionId": 2
}
]
}
}Single Collateral Item (Workaround)
If you use the old payload, the system will automatically assign a position ID. If the loan has no collateral yet, it will take Position 1. If it already has one item, it will take Position 2, and so on. Here's a sample JSON payload:
{
"Collateral": {
"loanId": "515",
"a": "2017",
"b": "Suzuki",
"c": "VS750GLP",
"d": "Base",
"additional": "Information",
"collateralType": "collateral.type.car",
"vin": "JS1VR51A5H2151359",
"distance": "25000",
"bookValue": "2408.59",
"color": "White",
"gpsStatus": "collateral.gpsstatus.notinstalled",
"gpsCode": "NONE",
"licensePlate": "License Plate Number",
"gap": "1125.25",
"warranty": "1254"
}
}Payload Fields
The following items are options for the payload:
- loanId: The ID of the associated loan
- a: The first collateral field (determined in loan settings)
- b: The second collateral field (determined in loan settings)
- c: The third collateral field (determined in loan settings)
- d: The fourth collateral field (determined in loan settings)
- additional: Additional collateral information
- collateralType: The type of the collateral (see Collateral Collections for more information)
- vin: The VIN number for the collateral (applicable to automobiles only)
- distance: The distance (mileage) the collateral has travelled (applicable to automobiles only)
- bookValue: The book value of the collateral (applicable to automobiles only)
- color: The color of the collateral
- gpsStatus: The installation status of a GPS (applicable to automobiles, see Collateral Collections for more information)
- gpsCode: The code of the GPS unit installed in the collateral (applicable if a GPS is installed)
- licensePlate: The license plate number of the vehicle (applicable to automobiles only)
- gap: The GAP insurance policy amount
- warranty: The warranty amount
- positionId: The position of the collateral on the loan. This can be an integer between 1 and 50.
Response
Whether you use the multiple collateral payload or the single item workaround, you'll get a payload similar to this one:
{
"d": {
"__metadata": {
"uri": "http://beta-loanpro.simnang.com/api/public/api/1/odata.svc/Loans(id=469)",
"type": "Entity.Loan"
},
"id": 469,
"displayId": "ABD-122800255",
"title": "ABD-122800255",
"settingsId": 453,
"setupId": 472,
"insurancePolicyId": 0,
"collateralId": 0,
"linkedLoan": 0,
"modId": 0,
"modTotal": 0,
"humanActivityDate": "/Date(1623024000)/",
"created": "/Date(1581540107)/",
"lastMaintRun": "/Date(0)/",
"createdBy": 1607,
"active": 1,
"archived": 0,
"loanAlert": null,
"temporaryAccount": 0,
"deleted": 0,
"deletedAt": null,
"Insurance": {
"__deferred": {
"uri": "Loans(469)/Insurance"
}
},
"CustomFieldValues": {
"__deferred": {
"uri": "Loans(469)/CustomFieldValues"
}
},
"ChecklistItemValues": {
"__deferred": {
"uri": "Loans(469)/ChecklistItemValues"
}
},
"Documents": {
"__deferred": {
"uri": "Loans(469)/Documents"
}
},
"Collateral": {
"__deferred": {
"uri": "Loans(469)/Collateral"
}
},
"LoanSettings": {
"__deferred": {
"uri": "Loans(469)/LoanSettings"
}
},
"LoanSetup": {
"__metadata": {
"uri": "http://beta-loanpro.simnang.com/api/public/api/1/odata.svc/LoanSetup(id=472)",
"type": "Entity.LoanSetup"
},
"id": 472,
"loanId": 469,
"modId": 0,
"active": 0,
"apr": 681.15599999999995,
"aprForceSingle": 0,
"payment": 67.310000000000002,
"origFinalPaymentDate": "/Date(1584057600)/",
"origFinalPaymentAmount": 68.060000000000002,
"tilFinanceCharge": 3039.1199999999999,
"tilTotalOfPayments": 3539.1199999999999,
"tilLoanAmount": 500,
"tilSalesPrice": 3539.1199999999999,
"tilPaymentSchedule": "[{\"count\":52,\"payment\":68.060000000000002,\"startDate\":\"03\\/22\\/2019\"}]",
"regzCustomEnabled": 0,
"regzApr": 0,
"regzFinanceCharge": 0,
"regzAmountFinanced": 0,
"regzTotalOfPayments": 0,
"loanAmount": 500,
"discount": 0,
"underwriting": 0,
"loanRate": 699,
"loanRateType": "loan.rateType.annually",
"loanTerm": 52,
"moneyFactor": 0,
"residual": 0,
"contractDate": "/Date(1552435200)/",
"firstPaymentDate": "/Date(1553212800)/",
"scheduleRound": 8.5299999999999994,
"amountDown": 0,
"reserve": 0,
"salesPrice": 0,
"gap": 0,
"warranty": 0,
"dealerProfit": 0,
"taxes": 0,
"creditLimit": 0,
"reportingCreditLimit": 0,
"loanClass": "loan.class.consumer",
"loanType": "loan.type.installment",
"discountSplit": 1,
"paymentFrequency": "loan.frequency.weekly",
"calcType": "loan.calcType.simpleInterest",
"daysInYear": "loan.daysInYear.actual",
"interestApplication": "loan.interestApplication.betweenTransactions",
"begEnd": "loan.begend.end",
"firstPeriodDays": "loan.firstPeriodDays.actual",
"firstDayInterest": 1,
"discountCalc": "loan.discountCalc.rebalancing",
"diyAlt": 0,
"dueDateOnLastDOM": 0,
"dueDatesOnBusinessDays": "loan.businessduedates.disabled",
"daysInPeriod": "loan.daysinperiod.30",
"roundDecimals": 5,
"lastAsFinal": 1,
"nddCalc": "loan.nddCalc.standard",
"endInterest": "loan.endInterest.no",
"scheduleTemplate": 4,
"curtailmentTemplate": 0,
"feesPaidBy": "loan.feesPaidBy.date",
"useInterestTiers": 0,
"calcHistoryEnabled": 0,
"calcDatesEnabled": 0,
"graceDays": 10,
"lateFeeType": "loan.lateFee.1",
"lateFeeAmount": 30,
"lateFeePercent": 0,
"lateFeeCalc": "loan.lateFeeCalc.standard",
"lateFeePercentBase": "loan.latefeepercentbase.regular",
"rollLastPayment": 0,
"paymentDateApp": "loan.pmtdateapp.actual",
"suspendForecastTo": null,
"isSetupValid": true,
"usuryAlert": false,
"CustomFieldValues": {
"__deferred": {
"uri": "LoanSetup(472)/CustomFieldValues"
}
}
},
"Notes": {
"__deferred": {
"uri": "Loans(469)/Notes"
}
},
"Promises": {
"__deferred": {
"uri": "Loans(469)/Promises"
}
},
"Bankruptcies": {
"__deferred": {
"uri": "Loans(469)/Bankruptcies"
}
},
"Charges": {
"__deferred": {
"uri": "Loans(469)/Charges"
}
},
"Payments": {
"__deferred": {
"uri": "Loans(469)/Payments"
}
},
"LoanFunding": {
"__deferred": {
"uri": "Loans(469)/LoanFunding"
}
},
"Advancements": {
"__deferred": {
"uri": "Loans(469)/Advancements"
}
},
"Credits": {
"__deferred": {
"uri": "Loans(469)/Credits"
}
},
"DueDateChanges": {
"__deferred": {
"uri": "Loans(469)/DueDateChanges"
}
},
"CurtailmentDates": {
"__deferred": {
"uri": "Loans(469)/CurtailmentDates"
}
},
"StatusArchive": {
"__deferred": {
"uri": "Loans(469)/StatusArchive"
}
},
"Transactions": {
"__deferred": {
"uri": "Loans(469)/Transactions"
}
},
"EscrowCalculatedTx": {
"__deferred": {
"uri": "Loans(469)/EscrowCalculatedTx"
}
},
"ScheduleRolls": {
"__deferred": {
"uri": "Loans(469)/ScheduleRolls"
}
},
"StopInterestDates": {
"__deferred": {
"uri": "Loans(469)/StopInterestDates"
}
},
"APDAdjustments": {
"__deferred": {
"uri": "Loans(469)/APDAdjustments"
}
},
"DPDAdjustments": {
"__deferred": {
"uri": "Loans(469)/DPDAdjustments"
}
},
"LoanModifications": {
"__deferred": {
"uri": "Loans(469)/LoanModifications"
}
},
"EscrowAdjustments": {
"__deferred": {
"uri": "Loans(469)/EscrowAdjustments"
}
},
"EscrowTransactions": {
"__deferred": {
"uri": "Loans(469)/EscrowTransactions"
}
},
"EscrowSubsetOptions": {
"__deferred": {
"uri": "Loans(469)/EscrowSubsetOptions"
}
},
"EscrowCalculators": {
"__deferred": {
"uri": "Loans(469)/EscrowCalculators"
}
},
"EstimatedDisbursements": {
"__deferred": {
"uri": "Loans(469)/EstimatedDisbursements"
}
},
"Loans": {
"__deferred": {
"uri": "Loans(469)/Loans"
}
},
"LinkedLoanValues": {
"__deferred": {
"uri": "Loans(469)/LinkedLoanValues"
}
},
"LoanChilds": {
"__deferred": {
"uri": "Loans(469)/LoanChilds"
}
},
"RecurrentCharges": {
"__deferred": {
"uri": "Loans(469)/RecurrentCharges"
}
},
"PayNearMeOrders": {
"__deferred": {
"uri": "Loans(469)/PayNearMeOrders"
}
},
"Customers": {
"__deferred": {
"uri": "Loans(469)/Customers"
}
},
"Portfolios": {
"__deferred": {
"uri": "Loans(469)/Portfolios"
}
},
"SubPortfolios": {
"__deferred": {
"uri": "Loans(469)/SubPortfolios"
}
},
"EscrowSubsets": {
"__deferred": {
"uri": "Loans(469)/EscrowSubsets"
}
},
"RuleAppliedLoanSettings": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedLoanSettings"
}
},
"RuleAppliedChargeOff": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedChargeOff"
}
},
"RuleAppliedAPDReset": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedAPDReset"
}
},
"RuleAppliedChecklists": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedChecklists"
}
},
"RuleAppliedChangeDueDates": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedChangeDueDates"
}
},
"RuleAppliedStopInterest": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedStopInterest"
}
},
"RuleAppliedAccountTools": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedAccountTools"
}
},
"RuleAppliedCustomerTools": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedCustomerTools"
}
},
"RuleAppliedAutopay": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedAutopay"
}
},
"RuleAppliedLoanSetup": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedLoanSetup"
}
},
"RuleAppliedBankruptcy": {
"__deferred": {
"uri": "Loans(469)/RuleAppliedBankruptcy"
}
},
"Autopays": {
"__deferred": {
"uri": "Loans(469)/Autopays"
}
},
"ActionResultNotes": {
"__deferred": {
"uri": "Loans(469)/ActionResultNotes"
}
},
"LoanFundingTransactions": {
"__deferred": {
"uri": "Loans(469)/LoanFundingTransactions"
}
}
}
}