Create Loan Modification

This request allows you to create a loan modification.

General

This request is a bit different from our others listed here in our documentation. Instead of consisting on one request, the loan modification process requires several (pretty exciting, huh?). We'll explain the whole process and provide the requests you will need below. First, let's go over what loan modifications are.

A Loan Modification, like the name implies, is a change made to the settings of a loan. Loan Modifications are more than simple changes to a loan's terms, however; here's what you need to know about creating Loan Modifications:

  • A Loan Modification is a complex change made in the middle of a loan's life; it's essentially a new loan that is placed on top of an old loan.
  • This will fully reset values such as Change Due Dates, Suspend/Resume Interest, Days Past Due, Amount Past Due.
  • Changing loan values that have no effect on the amortization schedule such as sales tax, dealer profit, amount down, custom fields, or due dates should be made in other ways.
  • A Loan Modification can only be made on an activated loan, and the terms of activated loans are locked in and only editable via modifications.
  • Loan Modifications should be made only in specific circumstances. Please read the following warning before proceeding with the steps below:
Modification Warning

DO YOU REALLY WANT TO MODIFY THIS LOAN? If you want to simply edit loan values that have no effect on the amortization schedule (such as sales tax, dealer profit, amount down, custom fields, etc), you should use the Additional Information tool instead of performing a modification. If you are specifically changing payment due dates or amounts, use the change due date tool or schedule roll feature in Setup Terms.

If you want to edit any other loan values, simply inactivate this loan, edit the values, and save and activate the loan. Using this tool will reset the loan as of the modification date—meaning, as of the date, it's like creating a new loan merged with the history on the loan prior to the modification. This will fully reset values such as Change Due Dates, Suspend/Resume Interest, Days Past Due, Amount Past Due, etc. Also, keep in mind that you have to reset any escrow adjustments to apply post modification, as those are also modification specific values.

Step 1 - Transactions After Modification Date (Optional)

You may find it necessary to modify a loan previous to payments or other transactions, and you may want those transactions to apply after the proposed modification. There is an available endpoint that will show you which loan transactions apply after the proposed modification date. To see this information, send a the following endpoint:

GET https://loanpro.simnang.com/api/public/api/1/Loans({loanId})/Autopal.PreModTestLoan({modificationDate})

A successful response will look similar to the following:

{  
   "d":{  
      "payments":[  
         {  
            "id":"2928",
            "displayId":"5557",
            "date":"2019-04-17",
            "amount":100,
            "info":"04/17/2019 Credit/Debit Card"
         }
      ],
      "charges":[],
      "advancements":[],
      "credits":[]
   }
}

Step 2 - Modify the Loan

To create a loan modification, send the following request:

Make sure to replace {loanId} with the ID of the loan you're modifying and {modificationDate} with the modification date you will use. The date should be formatted as YYYY-MM-DD. While not required, if you are opting to have transactions apply after the modification date, you should include a payload that looks something like this:

POST https://loanpro.simnang.com/api/public/api/1/Loans({loanId})/Autopal.CreateModification({modificationDate})
{
    "persistentTransactions": {
        "payments": [
            "2928"
        ]
    },
    "modificationDate": "2018-12-28"
}

The persistentTransactions object should contain an array for each transaction type. The array should contain IDs as strings separated by commas (e.g. "1","2","3").

Step 3 - Get Loan Setup ID

Creating a modification will create a new loanSetup entity and assign it to the loan. To update the new loan setup, you will need the ID. To receive the ID, send a GET request to the following endpoint:

GET https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans({loanId})/LoanSetup

Be sure to replace {loanId} with the ID for the loan. The response should look something like this:

{  
   "d":{  
      "__metadata":{  
         "uri":"https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans(id=702)",
         "type":"Entity.Loan"
      },
      "LoanSetup": {
        "__metadata": {
        "uri": "https://loanpro.simnang.com/api/public/api/1/odata.svc/LoanSetup(id=861)",
        "type": "Entity.LoanSetup"
      },
      "id":702,
      "displayId":"LOAN597f93726b19f",
      "title":"LN - PHP SDK597f933a295d6",
      "settingsId":661,
      "setupId":861,  // 👈 This is the ID you're looking for.
      "insurancePolicyId":null,
      "collateralId":433,
      "linkedLoan":null,
      "modId":null,
      "modTotal":0,
      "humanActivityDate":"/Date(1555459200)/",
      "created":"/Date(1501532986)/",
      "lastMaintRun":"/Date(1555489226)/",
      "createdBy":806,
      "active":1,
      "archived":0,
      "loanAlert":null,
      "temporaryAccount":0,
      "deleted":0,
      "deletedAt":null,
      "_relatedMetadata":null,
      "_dynamicProperties":null
   }
}

In the example above, the setupId is 861. Once you have the loanSetup ID, you are ready to set the loan terms of the modification.

Step 4 - Update the Loan Setup

To update the new loan setup, send the following PUT request:

PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans({loanId})
{  
   "LoanSetup":{  
      "id":861, // <--- loan setup ID
      "loanId":702,
      "loanAmount":12345.67,
      "payment":500,
      "loanRate":5.9,
      "contractDate":"2019-02-19",
      "firstPaymentDate":"2019-03-20",
      "loanTerm":12,
      "__id":861, // <--- loan setup ID
      "__update":true
   },
   "__id":702, // <--- loan ID
   "__update":true
}

Be sure to replace {loanId} with the ID of the loan.

Step 5 - Roll the Payment (Optional)

You may want to roll the payment for the customer so it matches the original payment amount. This is achieved by sending a POST request:

POST https://loanpro.simnang.com/api/public/api/1/Loans({loanID})
{
  "amount": "100.00",
  "method": "loan.rollPayment.termExact"
}

Make sure to replace {loanId} with the ID of the loan.

Step 6 - Activate the Loan

The last step is to activate the loan. To activate it, send a POST request to the following endpoint:

POST https://loanpro.simnang.com/api/public/api/1/Loans({loanID})/AutoPal.Activate()

Make sure to replace {loanId} with the ID of the loan here as well. No payload is required for this request. If this request is successful, the process of modifying a loan is now complete.

Database

For information on Loan Modification database tables, see the following articles: