All Categories > LMS API > API – Add Collateral to a Loan

API – Add Collateral to a Loan

Updated 3 months ago by Jackson Stone

Introduction
Requests
Response

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)

If you don't know the loan's ID, see our article on Finding Loan and Customer IDs.

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

Here's the response for adding collateral, through either the collateral or loan endpoints:

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