API – Add Collateral to a Loan
Updated 1 week ago
Introduction
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:
PUT 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. Here's a sample endpoint (be sure to replace the "515" with the ID of the loan you're working with):
PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans(515)
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
}
]
}
}Multiple Collateral with Custom Fields
The above payload won't let you add custom fields to your collateral. This is because the custom fields are nested within the collateral, and the collateral items are in turn nested in the loans. This box-in-a-box setup can't all be added at one time, but we can get around that if we instead send a POST request to the collateral endpoint:
POST https://staging-loanpro.simnang.com/api/public/api/1/odata.svc/Collateral()
Here's the JSON payload:
{
"Collateral": {
"results": [
{
"collateralType": "collateral.type.consumer",
"a": "2021",
"b": "Signature",
"c": "54821",
"d": "SCHENECTADY",
"additional": "Deluxe Model",
"color": "Iced Gold",
"warranty": "",
"loanId": "515",
"positionId": 2
"CustomFieldValues": {
"results": [
{
"customFieldId": 584,
"customFieldValue": "1"
},
{
"customFieldId": 585,
"customFieldValue": "22.00"
}
]
}
}
]
}
}Rather than entering the Loan ID in the endpoint itself, it's within the collateral object.
Single Collateral Item (Workaround)
If you want to add a single collateral item, you can actually use the old payload from before the update that added multiple collateral. 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. Just like the multiple collateral payload, you'll send a PUT request to the loans endpoint (switching "515" for your loan ID):
PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans(515).
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"
}
}
}
}