API – Loan Checklist
Introduction
Over the life of the loan, lenders may need to keep track of certain tasks or actions that have or have not happened. This could be things like, "send loan paperwork to the borrower" or "verify borrower employment". The checklist feature makes it easy to mark actions complete for a loan, and search for loans where actions have or have not been checked.
This article covers using checklist items and checklist item values (whether items are checked) for existing loans.
Checklist Items
Checklists can be configured in Settings > Loan > Checklist inside the Loan Management System (LMS) user interface. Configuration includes adding, updating, and removing checklists and checklist items. A checklist item is an individual task.
Checklists are configured at the tenant level, while values for the checklist items are recorded for individual loans. This may be a source of confusion when working with the API.
Pulling Checklist item Values
To pull checklist item values, use one of the following calls:
GET https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans({loanId})/ChecklistItemValues
GET https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans({loanId})?$expand=ChecklistItemValues
The first call will get just the checklist values for the loan, while the second will get loan values and expand the checklist values.
Because values don't exist before they are created, you may wonder how you can check which items are checked and which are not checked on a loan. This is easy, since any nonexistent value will be not checked. However, if you want to compare all values on a loan to all the checklist items that exist in the tenant, you will have to create a hard-coded array or object of the checklist items that appear in the LMS user interface in Settings > Loan > Checklist.
If you choose to create an array or object for comparison, make sure checklists and checklist items are linked to the IDs assigned by LMS. This will make it possible to associated values with checklist items.
Example
Here is an example of how a checklist object might look in JSON. This is only an example, so, if you choose to do this, structure it in whatever way makes the most sense:
{
"1": {
"checklistName": "borrowerDeceased", //name of the checklist
"checklistItemValues": {
"9": "Deceased Notification Received", // 9 is the ID of the checklist item assigned by LMS
"12": "Deceased Confirmation", // 12 is the ID of the checklist item assigned by LMS
}
},
{
"2": {
"checklistName": "covidRelief", //name of the checklist
"checklistItemValues": {
"5": "Covid Relief - Accepted", // 5 is the ID of the checklist item assigned by LMS
"6": "Covid Relief - Applied" // 6 is the ID of the checklist item assigned by LMS
}
}
}
}
Here is the response payload from the odata.svc/Loans() endpoint:
{
"d": {
"results": [
{
"__metadata": {
"uri": "http://loanpro.simnang.com/api/public/api/1/odata.svc/ChecklistItemValues(id=15)",
"type": "Entity.ChecklistItemValue"
},
"Checklist": {
"__deferred": {
"uri": "ChecklistItemValues(id=15)/Checklist"
}
},
"id": 15, // ID of the checklist item value
"entityId": 667, // loan ID
"entityType": "Entity.Loan", // type of the associated entity
"checklistId": 1, // id of the checklist
"checklistItemId": 9, // checklist item ID assigned by LMS
"checklistItemValue": 1, // checklist item value (1 = checked, 0 = unchecked)
"lastUpdated": "/Date(1641413841)/"
}
],
"summary": {
"start": 0,
"pageSize": 50,
"total": 1
}
}
}
The checklistId
from the response will correspond to one of the checklist identifiers from the array or object. The checklistItemId
from the response will correspond with one of the property names from your array or object, helping to associate the values. Any items that have never been checked, will not show in the response, so for a complete list, merge the response object with the object you created that contains all the checklist items.
Modifying Checklist Item Values
To modify the checklist for a loan, you will need to send a PUT request to the URL of the desired loan. For example, to modify the loan with the id 515, the URL would be
https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans(515).
Request Body
{
"ChecklistItemValues": {
"results": [
{
"checklistId": 1,
"checklistItemId": "8",
"checklistItemValue": 1
}
]
}
}
- checklistId – The ID of the checklist
- checklistItemId – The ID of the item on the checklist
- checklistItemValue – The value to set the checklist item to (1 = checked, 0 = unchecked)