Construction Loan Module - Response

The Data object for a response from the Construction 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

Objects: 🟥 Errors[], 🟥 Warnings[], 🟥 Results, 🟦 FedBox, 🟦 TILARESPA2015, 🟦 Moneys, 🟦 Accrual, 🟦 PmtStreams[], 🟦 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.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" : "Construction",
  "Data" : {
    "//" : "This is a comment.",
    "Hello" : "Friend!",
    "How" : "are you?"
  }
}

{
  "Result" : 200,
  "Module" : "Construction",
  "Data" : {
    "Errors" : [
      "Data.LoanDate (StringDate) not found.",
      "Data.PmtDate (StringDate) not found.",
      "Data.Term (StringInt) not found.",
      "Data.IntRate (StringFloat) not found.",
      "Data.Proceeds (StringFloat) not found."
    ],
    "Warnings" : [
      "Request field Data.Hello (String) not recognized.",
      "Request field Data.How (String) not recognized."
    ]
  }
}

🟦 Data.Results

This field(s) of this object represent the most important numerical results for the loan request.

Fields: 🔸Payment,

Objects: None

🔸 Data.Results.Payment

The loan payment is shown here.

🟦 Data.FedBox

This object groups together all fields which contain important numerical information, as defined in the Truth-In-Lending laws (Regulation Z).

Fields: 🔸AmtFin, 🔸FinChg, 🔸TotPmts, 🔹TotalSalePrice

Objects: 🟥 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.TotalSalePrice

The sum of the total of payments plus the total down payment. Please note that if no TotalDown field was included in the request, then this element will not be present.

🟥 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 returns the maximum APR as configured in the account's setup files. If no maximum APR has been specified, then this field will not be present in the response. The value of this field should be displayed as a percentage.

🔹 Data.FedBox.APR.MaxExceeded

If a maximum APR is configured in the account's setup files, then the value of this field indicates whether or not the current loan exceeds the maximum APR. If no maximum APR has been specified, then this field will not be present in the response.

🔸 Data.FedBox.APR.Type

This field returns the APR method u sed 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 Settings.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.

Fields: 🔸Principal, 🔸Interest, 🔹FinFees, 🔹Prepaid, 🔹PocketFees, 🔹MAPRFees, 🔹MinIntChgAdj, 🔹MinFinChgAdj

Objects: 🟦 ODI, 🟦 Fees[]

🔸 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.

🔹 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.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.MinIntChgAdj

If a minimum interest charge is configured in the account's setup files and the final payment was adjusted to meet this minimum interest charge, then this field will be returned in the response and will contain the value of the minimum interest charge adjustment.

🔹 Data.Moneys.MinFinChgAdj

If a minimum finance charge is configured in the account's setup files and the final payment was adjusted to meet this minimum finance charge, then this field will be returned in the response and will contain the value of the minimum finance charge adjustment.

🟦 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: 🔹AddToPmt, 🔸Count, 🔸Fee, 🔹Months, 🔹DailyCost

Objects: None

🔹 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.Count

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

🔸 Data.Moneys.ODI.Fee

Discloses the total amount odd days interest charge.

🔹 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.Fees[]

If the requested loan included fees, then for each fee in the loan 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, then the Moneys.Fees[] 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.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: 🔸Method, 🔸Days1Pmt, 🔸DayCount, 🔸Maturity

Objects: None

🔸 Data.Accrual.Method

The Method field contains a textual description of the interest accrual method used to compute the loan (e.g. "Unit Period 365 Simple".)

🔸 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 two methods as specified in by Accrual.DayCount (below).

🔸 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 method use a 360 day calendar.

🔸 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 with 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" : "1",
        "Pmt" : "10062.59",
        "Rate" : "4.500",
        "Begin" : "2023-09-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: 🔸Term, 🔸Pmt, 🔸Rate, 🔸Begin

Objects: Note

🔸 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[].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.AmTable

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

Fields: 🔹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, 🔹CLTot, 🔹AHTot, 🔹IUTot

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.GrandTotals.CLTot

The CLTot field will only appear on loans with certain types of life protection products, such as those based on a monthly outstanding balance. It contains the total amount paid for life over the duration of the loan.

🔹 Data.AmTable.GrandTotals.AHTot

The AHTot field will only appear on loans with certain types of disability or debt protection products, such as those based on a monthly outstanding balance. It contains the total amount paid for this protection over the duration of the loan.

🔹 Data.AmTable.GrandTotals.IUTot

The IUTot field will only appear on loans with certain types of involuntary unemployment protection products, such as those based on a monthly outstanding balance. It contains the total amount paid for this protection over the duration of the loan.

🟦 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, 🔹CLSub, 🔹AHSub, 🔹IUSub

Objects: None

🔸 Data.AmTable.SubTotals[].Year

The calendar year for which the subtotal data is applicable.

🔸 Data.AmTable.SubTotals[].Start

This field defines the first amortization event which falls in the specified calendar year. To find the AmLines[] object which corresponds to this value, match the Idx field of the AmLine object.

🔸 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.SubTotals[].CLSub

The CLSub field will only appear on loans with certain types of life protection products, such as those based on a monthly outstanding balance. It contains the total amount paid for life during the year.

🔹 Data.AmTable.SubTotals[].AHSub

The AHSub field will only appear on loans with certain types of accident and health or debt protection products, such as those based on a monthly outstanding balance. It contains the total amount paid for this protection during the year.

🔹 Data.AmTable.SubTotals[].IUSub

The IUSub field will only appear on loans with certain types of involuntary unemployment protection products, such as those based on a monthly outstanding balance. It contains the total amount paid for involuntary unemployment during the year.

🟥 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, 🔸Date, 🔸BegBal, 🔸Pmt, 🔸Int, 🔸Prin, 🔹CL, 🔹AH, 🔹IU, 🔹UnpaidInt, 🔸EndBal

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[].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.

🔸 AmData.AmTable.AmLines[]ine.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[].CL

The CL field will only appear on loans with certain types of life protection products, such as those based on a monthly outstanding balance. It contains the amount of the payment which is marked for life coverage.

🔹 Data.AmTable.AmLines[].AH

The AH field will only appear on loans with certain types of accident and health or debt protection products, such as those based on a monthly outstanding balance. It contains the amount of the payment which is marked for disability / debt protection coverage.

🔹 Data.AmTable.AmLines[].IU

The IU field will only appear on loans with certain types of involuntary unemployment protection products, such as those based on a monthly outstanding balance. It contains the amount of the payment which is marked for this coverage.

🔹 Data.AmTable.AmLines[].UnpaidInt

This field will only appear on an amortization line when interest has been accrued, but has not yet been paid or added to the principal balance. 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.