Loan Module - Response

The Data object for a response from the Loan module is defined below, in the order the fields are returned:

🟥 Data

The Data object encapsulates the response data for a given module, and will always be present.

Fields: 🔹Country, 🔹CurrencyDP

Objects: 🟥 Errors[], 🟥 Warnings[], 🟥 Notes[], 🟦 FedBox, 🟦 TILARESPA2015, 🟦 Moneys, 🟥 Accrual, 🟥 PmtStreams[], 🟦 Protection, 🟦 AmTable

🔹 Data.Country

If the request specified a two-character or three-digit Country code, then this field will be present and will contain the full name of the country associated with the specified code. Please see the Countries Appendix for the list of supported countries and their associated codes.

🔹 Data.CurrencyDP

If the number of decimal places allowed for currency values used in the request is a value other than 2, then this field will be present and will inform the application parsing the output of the correct value. If this field is not present, then the number of decimal places allowed for currency values used in the request is 2.

🟥 Data.Errors[]

The Errors[] field contains an Array of Strings which describe any errors encountered while handling the request. If the length of the Errors[] Array is zero (0), then the module processed the request successfully, and the Data object can be further processed by the calling application for the returned data.

On the other hand, if the length of the Errors[] Array is greater than zero (0), then this indicates that an error condition has been detected, and the calling application should not process the respons Data object further. In this case, the contents of the Errors[] array will describe the error(s) encountered.

Typical errors include the omission of 🟥 required fields, invalid field values, etc.

🟥 Data.Warnings[]

The Warnings[] field contains an Array of Strings which describe any warnings generated by the module handling the request. The most common warnings returned by modules inform the calling application that the module does not recognize a specified field (which may help to isolate a field name spelling error in the calling application's code). Note that field names which start with "//" will bre treated as comment fields by the SCE, and no warnings will be generated for these unrecognized fields.

Example - Request and response illustrating warnings when passing unrecognized fields:

{
  "Module" : "Loan",
  "Data" : {
    "//" : "This is a comment.",
    "Hello" : "Friend!",
    "How" : "are you?"
 }
}

{
  "Result" : 200,
  "Module" : "Loan",
  "Data" : {
    "Errors" : [
      "Data.Advances[] (Array) not found.",
      "Data.AccrualConfigs[] (Array) not found."
    ],
    "Warnings" : [
      "Request field Data.Hello (String) not recognized.",
      "Request field Data.How (String) not recognized."
    ]
 }
}

🟥 Data.Notes[]

The Notes[] field contains an Array of Strings which present important calculation comments to more fully explain the loan calculation results that may either not be apparant in the inputs or have overriden input assumptions. These notes are thoroughly detailed in the Calculation Notes Appendix.

🟦 Data.FedBox

This object groups together all fields which contain important numerical information, as defined in the Truth-In-Lending laws (Regulation Z). This object will not be present if BusinessRules.AmortizeOnly is set to true in the request.

Fields: 🔸AmtFin, 🔸FinChg, 🔸TotPmts

Objects: 🟦 TAP, 🟥 APR, 🟦 MAPR

🔸 Data.FedBox.AmtFin

The Regulation Z Amount Financed, which is defined as the amount of credit provided to the borrower or on their behalf.

🔸 Data.FedBox.FinChg

This element contains the Regulation Z Finance Charge, described as the dollar amount the credit extension will cost the borrower.

🔸 Data.FedBox.TotPmts

The amount which the borrower will have paid when the borrower has made all scheduled payments.

🟦 Data.FedBox.TAP

The TAP (total amount payable) object is only returned with the response if the value of the EditOutput.ShowTap request field is true.

Fields: 🔸Value, 🔹PrepaidNF, 🔹Pocket, 🔹TAP.PocketAPR

Objects: None

🔸 Data.FedBox.TAP.Value

The value of this field represents the total amount payable, and is computed as the sum of: (i) the total of payments, (ii) all non-financed APR affecting fees, (iii) all out-of-pocket non-APR affecting fees, and (iv) all out-of-pocket APR affecting fees.

🔹 Data.FedBox.TAP.PrepaidNF

The value of this field is the sum of all non-financed APR prepaid fees (APR affecting fees paid on the same date as an advance). This field will only be present if the value is greater than zero.

🔹 Data.FedBox.TAP.Pocket

The value of this field is the sum of all out-of-pocket non-APR affecting fees. This field will only be present if the value is greater than zero.

🔹 Data.FedBox.TAP.PocketAPR

The value of this field is the sum of all out-of-pocket APR affecting fees not paid on an advance. This field will only be present if the value is greater than zero.

🟥 Data.FedBox.APR

The APR object contains fields which return the value and APR method used.

Fields: 🔸Value, 🔹Max, 🔹MaxExceeded, 🔸Type

Objects: None

🔸 Data.FedBox.APR.Value

The computed APR, which is the cost of the extension of credit expressed as a yearly rate.

🔹 Data.FedBox.APR.Max

This field holds the maximum APR as specified in the input request (see Apr.Max). If not specified, this field (and the associated MaxExceeded field) will not be present in the response. The value of this field should be displayed as a percentage. As an example, for "Max" : "24.000", you would disclose a maximum APR of 24%.

🔹 Data.FedBox.APR.MaxExceeded

The value of this field indicates whether or not the current loan exceeds the specified maximum APR. As an example, if the maximum APR has been set to 24% and the APR for the returned loan was 25.512%, the APR object would be:

{
  "APR" : {
    "Value" : "25.512",
    "Max" : "24.000",
    "MaxExceeded" : true,
    "Type" : "Actuarial"
 }
}

🔸 Data.FedBox.APR.Type

This field returns the APR method used to compute the reported APR.

🟦 Data.FedBox.MAPR

The MAPR (military APR) object is only returned with the response if the value of the Apr.UseMAPR request field is true.

Fields: 🔸Value, 🔸Advance, 🔸Max, 🔸MaxExceeded

Objects: None

🔸 Data.FedBox.MAPR.Value

The computed military APR.

🔸 Data.FedBox.MAPR.Advance

This field returns the equivalent of the Amount Financed for the Military APR. Specifically, it is the principal balance less any MAPR fees, debt protection, etc.

🔸 Data.FedBox.MAPR.Max

This field holds the maximum Military APR as specified in the input XML (see Apr.MAPR_Max). If not specified, a default value of 36% is assumed. The value of this field should be displayed as a percentage. As an example, for "Max" : "36.000", you would disclose a maximum Military APR of 36%.

🔸 Data.FedBox.MAPR.MaxExceeded

The value of this field indicates whether or not the current loan exceeds the maximum allowed Military APR. As an example, if the maximum APR has been set to 36% and the Military APR for the returned loan was 37.125%, the MAPR object would be:

{
  "MAPR" : {
    "Value" : "37.125",
    "Advance" : "1350.00",
    "Max" : "36.000",
    "MaxExceeded" : true
 }
}

🟦 Data.TILARESPA2015

This object contains fields which are of interest to fulfilling the 2015 TILA RESPA rule. It will only be present if the TILARESPA2015 field in the request is set to true.

Fields: 🔸TotalLoanCost, 🔸CD_TotPmts, 🔸TIP

Objects: 🟥 LoanCosts[], 🟥 In5Years, 🟥 MaxPnIPmt, 🟥 MinRate, 🟥 MaxRate, 🟥 ProjectedPaymentsTable[]

🔸 Data.TILARESPA2015.TotalLoanCost

The value of this field is the sum of all borrower paid loan costs. Since all LoanCost values are rounded dollar amounts, the value of this element will also be a rounded dollar amount.

🔸 Data.TILARESPA2015.CD_TotPmts

This field returns the sum of the total of payments, all borrower paid loan costs, and any odd days interest that is prepaid at loan closing. This value should be disclosed on the Closing Disclosure form in the Total of Payments field.

🔸 Data.TILARESPA2015.TIP

The total interest percentage, rounded to three or fewer decimal places - as required.

🟥 Data.TILARESPA2015.LoanCosts[]

For every object in the Fees[] array present in the request which has its IsLoanCost field set to true (and hence, is a borrower paid loan cost) and whose amount is greater than zero (except odd days interest fee types, as explained in the previous documentation of the Fee and object), there will be a corresponding LoanCost object.

Fields: 🔹Name, 🔹In5Years, 🔸Value

Objects: None

🔹 Data.TILARESPA2015.LoanCosts[].Name

If a name was provided for the fee, then it will be included here in the disclosure for identification purposes.

🔹 Data.TILARESPA2015.LoanCosts[].In5Years

If the entire amount of the fee is different from the amount collected over the first five years (for example, a service charge), then this field will be present and disclose the portion of this loan coast that is accrued during the first five years.

🔸 Data.TILARESPA2015.LoanCosts[].Value

The value of this field is the numerical value of the fee, rounded to the nearest dollar.

🟥 Data.TILARESPA2015.In5Years

This object contains all important values required for the new "In 5 Years" section of the disclosure.

Fields: 🔸PaidTotal, 🔸PaidPrincipal

Objects: None

🔸 Data.TILARESPA2015.In5Years.PaidTotal

This field holds the sum of all "principal, interest, mortgage insurance, and borrower paid loan costs scheduled to be paid through the end of the 60th month after the due date of the first periodic payment". Note that this value is rounded to the nearest whole dollar.

🔸 Data.TILARESPA2015.In5Years.PaidPrincipal

This field holds "the principal scheduled to be paid through the end of the 60th month after the due date of the first periodic payment". Note that this value is rounded to the nearest whole dollar.

🟥 Data.TILARESPA2015.MaxPnIPmt

The fields of this object hold the maximum sceduled principal and interest payment during the term of the loan, as well as the date on which that payment is made.

Fields 🔸Date, 🔸Amount

Objects: None

🔸 Data.TILARESPA2015.MaxPnIPmt.Date

The value of this field returns the date on which the maximum scheduled principal and interest payment is made. If the maximum scheduled payment occurs more than once, then the date returned is that of the first instance.

🔸 Data.TILARESPA2015.MaxPnIPmt.Amount

The maximum sceduled principal and interest payment during the term of the loan.

🟥 Data.TILARESPA2015.MinRate

The fields of this object hold information regarding the minimum possible interest rate applied during the term of the loan.

Fields: 🔸Rate, 🔸Idx

Objects: None

🔸 Data.TILARESPA2015.MinRate.Rate

The value of the minimum interest rate applied during the term of the loan.

🔸 Data.TILARESPA2015.MinRate.Idx

This field returns the payment number for which the minimum rate is first applicable.

🟥 Data.TILARESPA2015.MaxRate

The fields of this object hold information regarding the maximum possible interest rate applied during the term of the loan.

Fields: 🔸Rate, 🔸Idx

Objects: None

🔸 Data.TILARESPA2015.MaxRate.Rate

The value of the maximum interest rate applied during the term of the loan.

🔸 Data.TILARESPA2015.MaxRate.Idx

This field returns the payment number for which the maximum rate is first applicable.

🟥 Data.TILARESPA2015.ProjectedPaymentsTable[]

Fields: 🔸Num, 🔸Title, 🔸YearStart, 🔸YearEnd, 🔸PnIPmtMin, 🔸PnIPmtMax, 🔸IntOnly, 🔸Balloon, 🔸MIPmt, 🔸TotalPmtMin, 🔸TotalPmtMax

Objects: None

This field returns an Array of projected payment table columns (PPCol), with each array member detailing a single column. Per the regulation, there will be a minimum of one column and a maximum of four columns, depending upon the parameters of the loan.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].Num

The value of this field identifies the number of the column to which the following fields apply. The value will be from 1 to 4.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].Title

The value of this field is the title for the column. Most of the time, it will be in the form of Years X - Y, or Year X, or Final Payment in the case of a final balloon payment.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].YearStart

The beginning year number for which this column data applies.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].YearEnd

The ending year number for which this column data applies.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].PnIPmtMin

The minimum principal and interest payment for this column.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].PnIPmtMax

The maximum principal and interest payment for this column.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].IntOnly

If none of the payments associated with this column are interest only payments, then the value of this field will be none. A value of some means that some of the payments (but not all) associated with this columnt are interest only. Finally, a value of all indicates that all payments associated with this columnt are interest only.

Note that for the purposes of this field, a scheduled payment is considered an interest only payment if the payment amount pays off all interest due at the time of the payment, with no reduction in the principal balance.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].Balloon

If any of the payments associated with this column are balloon payments (e.g. isolated payments that are more than twice the value of a regular periodic payment), then the value of this field will be true.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].MIPmt

The value of this field holds the mortgage insurance premium associated with this column, rounded to the nearest dollar. If no mortgage insurance is present or coverage has been dropped, a value of zero will be present.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].TotalPmtMin

This field returns the minimum estimated total payment for this column. Note that this value does not include any estimated escrow, as the SCE does not support escrow calculations. The calling application will need to increase these values by the estimated escrow amounts if any are present.

🔸 Data.TILARESPA2015.ProjectedPaymentsTable[].TotalPmtMax

This field returns the maximum estimated total payment for this column. Note that this value does not include any estimated escrow, as the SCE does not support escrow calculations. The calling application will need to increase these values by the estimated escrow amounts if any are present.

🟦 Data.Moneys

This element groups together those other major cash result amounts not disclosed under the FedBox object, such as the principal balance, interest charge, and fee amounts. This object will not be present if BusinessRules.AmortizeOnly is set to true in the request.

Fields: 🔸Proceeds, 🔸Principal, 🔸Interest, 🔹FinFees, 🔹Prepaid, 🔹OthNonAprFees, 🔹ServiceChg, 🔹PocketFees, 🔹MAPRFees, 🔹BalAdjTot, 🔹MinIntChgAdj, 🔹MinFinChgAdj, 🔹MortIns

Objects: 🟦 ODI, 🟦 Advances[], 🟦 Fees[], 🟦 ConInterest

🔸 Data.Moneys.Proceeds

This field represents the sum of all Advance amounts.

🔸 Data.Moneys.Principal

The principal balance is the amount on which interest is accrued. The principal balance consists of all advances requested by the borrower, as well as any fees and/or protection products which are financed.

🔸 Data.Moneys.Interest

This value of this field holds the total interest accrued during the term of the loan, assuming the borrower will make all scheduled payments. This field may be less than zero if the interest rate is less than zero.

🔹 Data.Moneys.FinFees

This field contains the sum of all fees having AddToPrin set to true and occuring on the date of an advance. If this value is zero, the field will not appear in the response.

🔹 Data.Moneys.Prepaid

This field represents all prepaid finance charges and contains the sum of all fees occurring on an advance and having AddToFinChg set to true. If this value is zero, the field will not be found in the response.

🔹 Data.Moneys.OthNonAprFees

This field contains the sum of all fees having AddToPrin set to true not occuring on the date of an advance. If this value is zero, the field will not be present in the response.

🔹 Data.Moneys.ServiceChg

This field represents all service charge fees and contains the sum of all fees not occurring on an advance and having AddToFinChg set to true. If this value is zero, the field will be omitted from the response.

🔹 Data.Moneys.PocketFees

This field holds the sum of all fees which are neither financed, nor added to the finance charge. In essence, they are paid out of the borrower's pocket. If no out of pocket fees were requested, then this field will not show up in the response.

🔹 Data.Moneys.MAPRFees

This field holds the sum of all fees which are Military APR fees (including protection products), and will only appear if the Military APR has been requested.

🔹 Data.Moneys.BalAdjTot

This field holds the sum of all balance adjustments occuring during the course of a loan. This field holds the sum of all actual dollar adjustment amounts, not Target amounts.

🔹 Data.Moneys.MinIntChgAdj

When a minimumm interest charge is assigned as a BusinessRule using the BusinessRules.MinIntChg field, the adjustment required to achieve that objective is shown in this field.

🔹 Data.Moneys.MinFinChgAdj

When a minimum finance charge is assigned as a BusinessRule using the BusinessRules.MinFinChg field, the adjustment required to achieve that objective is shown in this field.

🔹 Data.Moneys.MortIns

This field holds the total mortgage insurance fee, if not single premium. If mortgage insurance is not requested, or if it is requested but is not treated as single premium, then this field will not be included in the response.

🟦 Data.Moneys.ODI

This object, if present, contains information regarding odd days interest. If no odd days interest was requested, then this object will not be present in the response.

Fields: 🔸Count, 🔹Months, 🔹DailyCost, 🔹AddToPmt, 🔸Fee

Objects: None

🔸 Data.Moneys.ODI.Count

Discloses the number of odd days computed by the SCE for the requested loan.

🔹 Data.Moneys.ODI.Months

This field holds the number of odd months computed by the SCE for the requested loan when using odd days accrual method 250. If the odd days accrual method is a value other than 250, then this field will not be present in the ODI object of the response.

🔹 Data.Moneys.ODI.DailyCost

If the odd days interest fee is computed using a rounded daily cost, then the value of this field will hold that value. If the odd days interest is not computed using a rounded daily cost, then this field will not be present in the response.

🔹 Data.Moneys.ODI.AddToPmt

If the odd days interest has been added to the first payment, then this field will be present in the response with a value of true. If the odd days interest has been treated as a prepaid finance charge, then this field will not be present and a default value of false should be assumed.

🔸 Data.Moneys.ODI.Fee

Discloses the total amount odd days interest charge.

🟦 Data.Moneys.Advances[]

If the requested loan computed any advance amounts (see the Advance.Compute field for more information), then for each Advance in the loan there will be an Advance object in this array containing the date of the advance and the computed advance amount.

If all of the loan's advances were specified and not computed, then this array will not be included in the response.

Fields: 🔸Date, 🔸Amount

Objects: None

🔸 Data.Moneys.Advances[].Date

The date on which the advance is made.

🔸 Data.Moneys.Advances[].Amount

Discloses the computed advance amount.

🟦 Data.Moneys.Fees[]

If the requested loan computed any requested fees with the loan, and if EditOutput.ShowFees is set to true, then for each Fee in the loan request there will be a Fee object in this array containing the name of the fee and the computed fee amount.

If there were no fees requested with the loan, or if EditOutput.ShowFees is set to false, then this array will not be included in the response.

Fields: 🔹Name, 🔸Fee

Objects: None

🔹 Data.Moneys.Fees[].Name

If a name was provided for the fee, then it will be included here in the disclosure for identification purposes.

🔸 Data.Moneys.Fees[].Fee

Discloses the computed fee amount.

🟦 Data.Moneys.ConInterest

This object holds the total estimated interest accrued during the construction period, and how the construction interest is treated in the disclosure. If no construction period was specified, then this object will not be present in the output.

Fields: 🔸IsPrepaid, 🔸Amount

Objects: None

🔸 Data.Moneys.ConInterest.IsPrepaid

If the construction interest is disclosed as interest only payments in the amortization schedule, then the value of this field will be set to false. Otherwise, the value of this field will be set to true.

🔸 Data.Moneys.ConInterest.Amount

Discloses the total amount of estimated interest accrued during the construction period.

🟥 Data.Accrual

This object groups together interest accrual information, such as the accrual method(s) used, days to the first payment and the loan's maturity date.

Fields: 🔸Methods[], 🔹YieldPPY, 🔸Days1Pmt, 🔸DayCount, 🔸Maturity

Objects: None

🔸 Data.Accrual.Methods[]

Each array member contains a textual description of the interest accrual method used to compute the loan (e.g. "Unit Period 365 Simple").

🔹 Data.Accrual.YieldPPY

If BusinessRules.YieldPPY in the loan's request is set to a value other than 0, then this field will be returned in the response with the same value passed into the request.

🔸 Data.Accrual.Days1Pmt

This field contains the number of days between the date of the first advance and the date of first payment, computed by one of three methods as specified in by Accrual.DayCount.

🔸 Data.Accrual.DayCount

This field specifies the method used to compute the number of days from the date of the first advance until the first payment date. Actual means that the actual number of days between these two dates are used, whereas the True360 and True365 methods use a 360/365 day calendar, respectively.

🔸 Data.Accrual.Maturity

Holds the maturity date of the loan, which is the date on which the last payment is scheduled. All dates are in the form of YYYY-MM-DD, and must be 10 characters long.

🟥 Data.PmtStreams[]

The PmtStreams[] array is made up of one or more PmtStream objects (there will always be at least one of these elements, and there may be more than one depending upon the loan type). The PmtStream objects describe the scheduled stream of payments for the computed loan. Instead of disclosing each and every payment individually (which can be done using the AmTable object), the payment stream groups together consecutive equal payments at the same interest rate to produce output along the lines of:

{
  "PmtStreams" : [
    {
      "Term" : "11",
      "Pmt" : "87.90",
      "Rate" : "10.000",
      "Begin" : "2019-02-01",
      "PPY" : "12"
   },
    {
      "Term" : "1",
      "Pmt" : "87.85",
      "Rate" : "10.000",
      "Begin" : "2020-01-01"
   }
  ]
}

Each object describes a single stream of equal payments at the same interest rate, using the following fields to define the important properties of each payment stream.

Fields: 🔹Idx, 🔸Term, 🔸Pmt, 🔹IsSplitRate, 🔹Rate, 🔸Begin, 🔹PPY,

Objects: None

🔹 Data.PmtStreams[].Idx

If the value of EditOutput.TagPmts is set to true in the loan request, then this field will appear for each PmtStreams[] object. The value of this field identifies which PmtStreams[] array member of the loan request gave rise to it.

If the value of this field is -1, then perfect amortization was enforced (e.g. the BusinessRules.AmError field of is set to AdjPmt).

If the value of this field is -2, then an early payoff event was triggered, which is caused by (i) specifying the EditOutput.EarlyPayoffDate field, or (ii) using whole dollar rounding which can shorten the specified term of the loan, or (iii) specifying a fixed or minimum payment amount which also may shorten the specified term of the loan.

🔸 Data.PmtStreams[].Term

The Term field holds the number of payments that make up the given payment stream.

🔸 Data.PmtStreams[].Pmt

The Pmt field holds the computed payment amount for this payment stream.

🔹 Data.PmtStreams[].IsSplitRate

If this payment stream accrued interest using split-rate tiers, then this field will be present and set to true. Otherwise, this field will not be returned and has an assumed default value of false.

🔹 Data.PmtStreams[].Rate

Contains the interest rate used for the duration of this payment stream. If this payment stream accrued interest using split-rate tiers, then this field will not be returned.

🔸 Data.PmtStreams[].Begin

This field identifies the date on which the first payment for this given payment stream is scheduled to be made. All dates are in the form of YYYY-MM-DD, and must be 10 characters long.

🔹 Data.PmtStreams[].PPY

If the value of the Term field is greater than one, then the periodic payment frequency for this payment stream is also disclosed.

🟦 Data.MI

If mortgage insurance is present on the requested loan, then this object and all required child field objects (documented below) will be included in the response.

Fields: 🔹UpFront

Objects: 🟥 Rates[], 🟦 Periodic

🔹 Data.MI.UpFront

The value of this field represents the up front fee paid for mortgage insurance. If there is no up front fee, then this field will not be present in the response.

🟥 Data.MI.Rates[]

Fields of each rate object disclose the rate, premium per year, and premium per period.

Fields: 🔸Rate, 🔸PremPerYear, 🔸PremPerPeriod

Objects: None

🔸 Data.MI.Rates[].Rate

The percentage rate used in the mortgage insurance calculation.

🔸 Data.MI.Rates[].PremPerYear

The annual mortgage insurance premium amount.

🔸 Data.MI.Rates[].PremPerPeriod

The periodic mortgage insurance premium amount.

🟦 Data.MI.Periodic

Fields of this object provide the loan to value ratio, as well as the payment indexes when the principal balance falls below the WarnLTV and DropLTV percentage values specified in the request. This element is only present if a corresponding Periodic field is found in the request.

Fields: 🔸LTV, 🔸IndexToWarn, 🔸IndexToDrop

Objects: None

🔸 Data.MI.Periodic.LTV

The loan to value ratio of the computed loan, expressed as a percentage.

🔸 Data.MI.Periodic.IndexToWarn

The value of this field indicates the payment index on which the remaining principal balance to home value ratio drops below the specified WarnLTV percentage.

🔸 Data.MI.Periodic.IndexToDrop

The value of this field indicates the payment index on which the remaining principal balance to home value ratio drops below the specified DropLTV percentage. Mortgage insurance coverage stops after this payment.

🟦 Data.Protection

If protection products are requested, then this object will be present in the response, along with the Products[] array which contains details on each requested protection product.

Fields: 🔸LoanType, 🔹Path

Objects: 🟥 Products[]

🔸 Data.Protection.LoanType

Protection products are often limited to certain types of loan repayment schedules, such as regular equal and balloon payment loans. Also, different formulas and various other settings may be used for different loan repayment types.

The value of this field returns the type of loan repayment schedule that the SCE determines after analyzing on the computed loan. Please see the samples provided with this documentation which illustrates how to create JSON requests which will fall under these loan repayment classifications.

🔹 Data.Protection.Path

This optional field will hold the value of the data path used by the SCE to find the required setup files for protection calculations. This field will only be present if the Protection.ShowDataPath field of the request is set to true.

🟥 Data.Protection.Products[]

For each distinct payment protection product that the calling application requested with a loan, a Product object will be returned.

Fields: 🔸Code, 🔸Result, 🔸Abbrev, 🔸Name, 🔹IsDP, 🔹Table, 🔹Formula, 🔹RateType, 🔹DropCode, 🔹DropReason

Objects: 🟦 Notes[], 🟦 Cost, 🟦 Coverage, 🟦 Benefit, 🟦 Borrowers[], 🟦 Caps

🔸 Data.Protection.Products[].Code

This field defines the type of payment protection product that this element, and all child fields, refers to. It mirrors the Product.Code field in the loan request, with the addition of the LL code which indicates a level credit life product.

🔸 Data.Protection.Products[].Result

The value of this field informs the calling application if the requested coverage has been fully provided, partially provided (i.e. one or more coverage caps have been exceeded and partial coverage has been extended), or completely dropped. If coverage has been dropped, then the Products[] object will not have any child objects (e.g. Product.Notes, Product.Cost, etc.).

🔸 Data.Protection.Products[].Abbrev

This field holds the protection product's abbreviation, as configured in the appropraite setup file.

🔸 Data.Protection.Products[].Name

This field holds the protection product's name, as configured in the appropraite setup file.

🔹 Data.Protection.Products[].IsDP

This field indicates if the product has been set up as debt protection. If this field is not present, then the default value of false should be used (which indicates that the product has been set up as insurance instead).

🔹 Data.Protection.Products[].Table

The Table field will only be present when a product is offered with differing tables of rates. If present, the value of this field is the table number used in the calculation.

🔹 Data.Protection.Products[].Formula

The Formula field contains an abbreviated description of the formula used to compute the desired protection product. The formula codes are for the use of the J. L. Sherman and Associates, Inc. support team. Please see this table of formula codes to see each formula code and description.

🔹 Data.Protection.Products[].RateType

This field will only be present in the output if the protection product has been configured to allow for coverage to switch from joint to single during the term of coverage, should one of the borrowers exceed an age at termination cap. If the field is not present, then a value of Fixed should be assumed as only one rate has been used in the protection calculation.

If this field is present, then there is the possibility that the rate used to compute the protection may have changed (in the case of coverage for one borrower ending while coverage for the other borrower continues). If this is the case, then the field will indicate this rate change with a value of Variable.

🔹 Data.Protection.Products[].DropCode

If the requested protection was dropped by the SCE for any reason, then the value of this field will be greater than zero. In this case, no child objects of Products[] object will be present.

A value of zero indicates that the requested product was included with the loan, and as such, the child objects of Products[] which describe the coverage details, should be parsed.

Please see the table of drop codes for a complete list of all drop codes and and their associated description.

🔹 Data.Protection.Products[].DropReason

If the requested protection product was successfully included in the loan, then the value of this field will be Valid Calculation and corresponds to a DropCode value of 0.

If the requested protection was dropped by the SCE for any reason (and hence, DropCode is > 0), then this field will provide a brief description of why the protection was dropped.

Please see the table of drop codes for a complete list of all drop codes and and their associated description.

🟦 Data.Protection.Products[].Notes[]

The Notes array may appear in the response to further clarify the product calculation methodology. Each note is associated with a numeric code and text return value. Please see the documentation for the Note object below.

Fields: 🔸Code, 🔸Note

Objects: None

🔸 Data.Protection.Products[].Notes[].Code

The unique integer identifying the protection product Note in question. This Code may be useful if the calling application would like to override the default description or check for a given Note's Code.

Please see the table of protection product notes for all codes and their associated descriptions.

🔸 Data.Protection.Products[].Notes[].Note

A text description of the Note. Please see the table of protection product notes for all codes and their associated descriptions.

🟦 Data.Protection.Products[].Cost

This object's fields detail the cost of the protection product in total, per payment, and per day. It also provides the rate used to compute the premiums.

Fields: 🔸Premium, 🔸PerPmt, 🔸PerDay, 🔸Rate, 🔹Factor

Objects: None

🔸 Data.Protection.Products[].Cost.Premium

The total cost for this protection over the term of the loan.

🔸 Data.Protection.Products[].Cost.PerPmt

The cost of coverage expressed as an amoun per payment.

🔸 Data.Protection.Products[].Cost.PerDay

The cost of coverage expressed as an amoun per day.

🔸 Data.Protection.Products[].Cost.Rate

The rate used to compute the premium for the requested protection product.

🔹 Data.Protection.Products[].Cost.Factor

The rate factor used to compute the premium for the requested protection product. Note that this field is only present if the Product.ShowFactor field of the associated protection product true.

🟦 Data.Protection.Products[].Coverage

The aggregate coverage amount, code, and note are provided in the fields of this object:

Fields: 🔸Amount, 🔸Code, 🔸Note

Objects: None

🔸 Data.Protection.Products[].Coverage.Amount

The aggregate coverage amount for this protection product.

🔸 Data.Protection.Products[].Coverage.Code

If the requested protection was capped by the SCE for any reason, then the value of this field will be greater than zero. A value of zero indicates that the requested product was included with the loan for the full coverage amount of the loan.

🔸 Data.Protection.Products[].Coverage.Note

This field will describe the type of coverage provided. If full coverage has been provided on the aggregate coverage, then the note will contain Full Coverage. Otherwise, the note will describe the type of partial coverage used.

🟦 Data.Protection.Products[].Benefit

Disability and involuntary unemployment provide coverage based upon a computed benefit amount. This object collects the monthly and periodic benefit amounts, as well as the benefit coverage code and note.

Fields: 🔸BenMon, 🔸BenPer, 🔸Code, 🔸Note

Objects: None

🔸 Data.Protection.Products[].Benefit.BenMon

The computed monthly benefit amount.

🔸 Data.Protection.Products[].Benefit.BenPer

The computed periodic benefit amount.

🔸 Data.Protection.Products[].Benefit.Code

If the benefit for the requested protection was capped by the SCE for any reason, then the value of this field will be greater than zero. A value of zero indicates that the requested product was included with the loan for the full benefit amount of the loan.

🔸 Data.Protection.Products[].Benefit.Note

This field will describe the type of benefit coverage provided. If full coverage has been provided on the benefit, then the note will contain Full Coverage. Otherwise, the note will describe the type of partial coverage used.

🟦 Data.Protection.Products[].Borrowers[]

This array provides the calling application with data about the term of coverage for the specified borrower(s), for the requested product.

Fields: 🔸Birthday, 🔸Pmts, 🔸Months, 🔹AmMonths, 🔸AgeAtIssue, 🔸AgeAtMaturity, 🔸Maturity, 🔸Code, 🔸Note

Objects: None

🔸 Data.Protection.Products[].Borrowers[].Birthday

The birthday associated with the borrower, as specified in the request. All dates are in the form of YYYY-MM-DD, and must be 10 characters long.

🔸 Data.Protection.Products[].Borrowers[].Pmts

The term of coverage expressed as a number of payments.

🔸 Data.Protection.Products[].Borrowers[].Months

The term of coverage expressed as a number of months.

🔹 Data.Protection.Products[].Borrowers[].AmMonths

This field is only be returned when the protection product is configured to use TruStage's single premium formula #5, and contains the computed amortization term used in the premium computation.

🔸 Data.Protection.Products[].Borrowers[].AgeAtIssue

The value of this field represents the age at issue of the borrower in a special date-like format of YYYY-MM-DD, where the borrower is YYYY years, MM months, and DD days old when coverage begins.

🔸 Data.Protection.Products[].Borrowers[].AgeAtMaturity

The value of this field represents the age at maturity of the borrower in a special date-like format of YYYY-MM-DD, where the borrower is YYYY years, MM months, and DD days old when coverage terminates.

🔸 Data.Protection.Products[].Borrowers[].Maturity

The coverage maturity date for this particular borrower.

🔸 Data.Protection.Products[].Borrowers[].Code

If the requested protection was truncated by the SCE for any reason, then the value of this field will be greater than zero. A value of zero indicates that the requested product was included with the loan for the full term of the loan.

🔸 Data.Protection.Products[].Borrowers[].Note

This field will describe the type of coverage provided. If full term coverage has been provided, then the note will contain Full Coverage. Otherwise, the note will describe the type of truncated coverage used.

🟦 Data.Protection.Products[].Caps

This object provides the calling application with data about the maximum terms, amounts, and ages associated with the requested product.

Fields: 🔹Coverage, 🔹Benefit, 🔹BenPer, 🔹Term, 🔹TermPer, 🔹InceptAge, 🔹AttainAge

Objects: None

🔹 Data.Protection.Products[].Caps.Coverage

Contains the maximum aggregate coverage amount, expressed in dollars. If no cap is present or applicable, then this field will not be present.

🔹 Data.Protection.Products[].Caps.Benefit

Contains the maximum monthly benefit amount. If no cap is present or applicable, then this field will not be present.

🔹 Data.Protection.Products[].Caps.BenPer

Contains the maximum periodic benefit amount. If no cap is present or applicable, or if the payment frequency of the requested loan is monthly, then this field will not be present.

🔹 Data.Protection.Products[].Caps.Term

Contains the maximum coverage term, expressed in months. If no cap is present or applicable, then this field will not be present.

🔹 Data.Protection.Products[].Caps.TermPer

Contains the maximum coverage term, expressed as a number of payments. If no cap is present or applicable, or if the payment frequency of the requested loan is monthly, then this field will not be present.

🔹 Data.Protection.Products[].Caps.InceptAge

Contains the maximum age a borrower may be at loan inception, expressed in years. If no cap is present or applicable, then this field will not be present.

🔹 Data.Protection.Products[].Caps.AttainAge

Contains the maximum age a borrower may attain during the term of the loan, expressed in years. If no cap is present or applicable, then then this field will not be present.

🟦 Data.AmTable

This object contains fields which summarize and describe the loan's amortization schedule. If EditOutput.ShowAmTable is set to false, then this object will not be found in the response.

Fields: 🔹AvgBal, 🔹Months, 🔹Weeks, 🔹OddDays

Objects: 🟦 GrandTotals, 🟦 SubTotals[], 🟦 AmLines[]

🔹 Data.AmTable.AvgBal

This field will only appear if a Canadian APR is disclosed for the computed loan. The value of this field is the average balance of the loan used in the Canadian APR calculation.

🔹 Data.AmTable.Months

This field will only appear if a Canadian APR is disclosed for the computed loan. The value of this field is the whole number of months in the term of the loan used in the Canadian APR calculation. Note that the term is expressed in monthly or weekly units, but never both.

🔹 Data.AmTable.Weeks

This field will only appear if a Canadian APR is disclosed for the computed loan. The value of this field is the whole number of weeks in the term of the loan used in the Canadian APR calculation. Note that the term is expressed in monthly or weekly units, but never both.

🔹 Data.AmTable.OddDays

This field will only appear if a Canadian APR is disclosed for the computed loan. The value of this field is the number of odd days in the term of the loan used in the Canadian APR calculation. Odd days are computed by moving backwards from the maturity date the number of disclosed months or weeks, and then counting the additional number of days required to land on the loan date.

🟦 Data.AmTable.GrandTotals

This object describes the total amounts of various categories throughout the life of the loan. As an example, the total amount paid to interest and principal, as well as the total of payments are all contained in fields of this object.

Fields: 🔸PmtTot, 🔸IntTot, 🔸PrinTot

Objects: None

🔸 Data.AmTable.GrandTotals.PmtTot

The total of payments scheduled for the computed loan.

🔸 Data.AmTable.GrandTotals.IntTot

The total amount paid to interest over the life of the loan, assuming all payments are made as scheduled.

🔸 Data.AmTable.GrandTotals.PrinTot

This field contains the total amount paid to principal during the loan term, assuming all payments are made as scheduled.

🟦 Data.AmTable.SubTotals[]

Describes the total amounts of various categories paid during a given calendar year. For each year in which the computed loan has scheduled payments, there will be a SubTotal object in the array.

Fields: 🔸Year 🔸Start, 🔸Events, 🔸PmtSub, 🔸IntSub, 🔸PrinSub

Objects: None

🔸 Data.AmTable.SubTotals[].Year

The calendar year for which the subtotal data is applicable.

🔸 Data.AmTable.SubTotals[].Start

This field defines the index of the first AmLine event in the AmLines[] array which falls in the specified calendar year.

🔸 Data.AmTable.SubTotals[].Events

This field defines the number of amortization events which belong to this calendar year.

🔸 Data.AmTable.SubTotals[].PmtSub

Contains the total of payments scheduled for the calendar year.

🔸 Data.AmTable.SubTotals[].IntSub

Holds the total amount paid to interest over the calendar year, assuming all payments are made as scheduled.

🔸 Data.AmTable.SubTotals[].PrinSub

Contains the total amount paid to principal during the calendar year, assuming all payments are made as scheduled.

🟦 Data.AmTable.AmLines[]

There is one AmLine object for each amortization event which occurs during the life of a loan. Most of the time, each event will describe a payment, and detail how that payment is applied (to interest, principal, loan protection products, etc.). Some events, such as capitalizing interest, will not have payments but will show how the loan amortizes.

Fields: 🔸Idx, 🔹Type, 🔸Date, 🔸BegBal, 🔸Pmt, 🔸Int, 🔸Prin, 🔹FeeTot, 🔹ProtUnpaid, 🔹PmtEsc, 🔹MI, 🔹UnpaidInt, 🔸EndBal, 🔹MinPnI, 🔹MinInt, 🔹MinPrin, 🔹MaxPnI, 🔹MaxInt, 🔹MaxPrin

Objects: None

🔸 Data.AmTable.AmLines[].Idx

The index of the amortization event, which is either the payment number, or zero. A value of zero designates an event that is either not a payment or is a skipped payment.

🔹 Data.AmTable.AmLines[].Type

The type of event is recorded in this field, such as Advance or FixedPmt. If any fees are included in the loan, then the value of this field for those fee events will be the Name of the fee, as specified in the request.

🔸 Data.AmTable.AmLines[].Date

The date on which the amortization event is scheduled to occur. All dates are in the form of YYYY-MM-DD, and must be 10 characters long.

🔸 Data.AmTable.AmLines[].BegBal

The principal balance before the amortization event occurs.

🔸 Data.AmTable.AmLines[].Pmt

The payment amount for this event.

🔸 Data.AmTable.AmLines[].Int

The amount of interest paid at this event.

🔸 Data.AmTable.AmLines[].Prin

The amount of principal paid at this event.

🔹 Data.AmTable.AmLines[].FeeTot

The total of all fees paid at this event.

🔹 Data.AmTable.AmLines[].ProtUnpaid

If the loan includes escrowed True MOB protection products, and if a payment is not sufficient to pay the accrued fees, then any unpaid protection fees will be carried forward in this field to be paid off as soon as possible in a future payment.

🔹 Data.AmTable.AmLines[].PmtEsc

If the computed loan is an annual rest mortgage, then the sum of escrowed payments for each amortization event will appear in this field. If the computed loan is not an annual rest mortgage, then this field will not be found in the response.

🔹 Data.AmTable.AmLines[].MI

The amount of mortgage insurance paid at this event.

🔹 Data.AmTable.AmLines[].UnpaidInt

Any interest not paid after this event is logged in this field.

If EditOutput.KeepSlush is set to true in the request, then the unpaid interest will always be displayed to four (4) decimal places.

If EditOutput.KeepSlush is set to false, then if the interest accrued has not yet been rounded, then the unpaid interest will be displayed to four (4) decimal placed. If rounded, then the unpaid interest is displayed to two (2) decimal places.

🔸 Data.AmTable.AmLines[].EndBal

The principal balance amount, after the amortization event has taken place.

🔹 Data.AmTable.AmLines[].MinPnI

If the Loan is an ARM loan which specified a minimum lifetime interest rate (see ARM.Limits.Floor), and if TILA RESPA data has been requested (using the TILARESPA2015 field), then this field will be present in each AmLine object that represents a payment. The value of this field represents the minimum principal and interest payment possible, should the index + margin rate trend towards the minimum lifetime rate after the teaser term has expired.

🔹 Data.AmTable.AmLines[].MinInt

The value of this field represents the amount of the MinPnI payment which has been used to pay interest. This field will only be present if the MinPnI field is present and if the request set TILARESPA2015.MinPnIDetails to true.

🔹 Data.AmTable.AmLines[].MinPrin

The value of this field represents the amount of the MinPnI payment which has been used to pay down the principal balance. This field will only be present if the MinPnI field is present and if the request set TILARESPA2015.MinPnIDetails to true.

🔹 Data.AmTable.AmLines[].MaxPnI

If the Loan is an ARM loan which specified a maximum lifetime interest rate (see ARM.Limits.Ceiling), and if TILA RESPA data has been requested (using the TILARESPA2015 field field), then this field will be present in each AmLine object that represents a payment. The value of this field represents the maximum principal and interest payment possible, should the index + margin rate trend towards the maximum lifetime rate after the teaser term has expired.

🔹 Data.AmTable.AmLines[].MaxInt

The value of this field represents the amount of the MaxPnI payment which has been used to pay interest. This field will only be present if the MaxPnI field is present and if the request set TILARESPA2015.MaxPnIDetails to true.

🔹 Data.AmTable.AmLines[].MaxPrin

The value of this field represents the amount of the MaxPnI payment which has been used to pay down the principal balance. This field will only be present if the MaxPnI field is present and if the request set TILARESPA2015.MaxPnIDetails to true.