API – Add Collateral to a Loan
Introduction
In LMS, up to 50 collateral items can be added to a loan. Once you've created a loan, you can add collateral one by one in the UI, or add them all at once with a single API request.
Requests
After the update which allowed for multiple collateral items to be added to a single loan, we altered the collateral payload to include a position ID for each collateral item. This identifier lets you add up to 50 collateral items in the same call.
There are actually three options for how to go about it in the API:
- Add multiple collateral in one call through the odata.svc/Loans() endpoint. This payload uses position IDs, but can't include custom fields.
- Add multiple collateral with custom fields through the odata.svc/Collateral() endpoint. This payload uses position IDs, and can include custom fields.
- Add a single collateral item with the legacy payload to the odata.svc/Loans() endpoint. This is the old payload from before the multiple collateral update, so it doesn't use 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
}
]
}
}
The one downside of this request is that you can't include custom fields. 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 using the odata.svc/Collateral() endpoint.
Multiple Collateral with Custom Fields
The main advantage of using the odata.svc/Collateral() payload is that you can add custom fields to your collateral items. 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 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 traveled (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. If you don't include a position ID, the system will automatically assign the next number up. |
Response
Whether you use the multiple collateral payload or the single item workaround, you'll get a similar response.
Expand Full Response
{
"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"
}
}
}
}