Qualified Mortgages - Request

Please see the Legend to understand the conventions used to document each object and field. Note that for requests, the XML objects are documented in alphabetical order by parent object.

🟥 Data

This is the root object of the QM request, and is required. This contains child objects which specify the particulars of the already computed loan which is being examined to see if the loan is QM compliant. The following fields and child objects of the Data object are as follows:

Fields: 🔹DataDirPath, 🔹QmType

Objects: 🟦 Format, 🟥 Lien, 🟥 LoanFeatures, 🟥 LoanData, 🟥 HcmResults, 🟦 SmallCreditorBalloon

🔹 Data.DataDirPath

If this field is set, the SCEX will look for a data folder containing the qm.ini file in the path specified. Thus, in the example above where DataDirPath is set to C:\SCEX\, the SCEX will look for the qm.ini file in C:\SCEX\data.

If the calling application wishes to specify the data directory path in its entirety (e.g. the calling app does not want the SCEX to append \data to the provided path), then simply terminate the specified DataDirPath with an asterisk (*). Thus, if the DataDirPath is set to C:\SCEX\bank1\*, the SCEX will look for the APOR files in C:\SCEX\bank1\.

If this field is not set, the SCEX will attempt to locate the data folder in the default data directory path location, which can be retrieved using the inVERSION query, and set via the SCEX API.

Since the qm.ini file is global in nature, you only need to have one copy of this file available even if your installation hosts multiple data paths for different clients.

🔹 Data.QmType

This field determines whether or not the APR less Apor threshold is enforced.

• General - APR less Apor threshold is enforced as requred in Section §1026.43(e)(2)(vi).

• SmallCreditor - As permitted in Section §1026.43(e)(5), small creditors have the enforcement of the APR less Apor threshold lifted.

A small creditor writing a balloon loan has additional loan constraints. Refer to the SmallCreditorBalloon object to signal a balloon loan written by a small creditor. See Section §1026.43(e)(6) for detailed legal definition on small creditor balloon loan exceptions.

Seasoned loans are not allowed in this module because of the amount of the volume of loan data necessary to make the determination.

🟦 Data.Format

The Format object is one of the first objects parsed from a request, as the fields of this empty object affect how date and numeric values are parsed and validated.

Fields: 🔹CurrencyDecimals, 🔹DateFormat, 🔹DateSeparator, 🔹DecimalSeparator, 🔹StrictDP, 🔹ThousandSeparator

Objects: None

🔹 Data.Format.CurrencyDecimals

When displaying and parsing Currency values, the value of this field determines the maximum number of decimal places allowed after the DecimalSeparator.

🔹 Data.Format.DateFormat

When displaying and parsing Date values, this field determines the expected format for all Date fields. The following DateFormat options are allowed:

• YMD - All dates should be formatted as YYYY-MM-DD.
• MDY - All dates should be formatted as MM-DD-YYYY.
• DMY - All dates should be formatted as DD-MM-YYYY.

Note that the character which separates the individual month, day, and year portions of the date is configurable via the DateSeparator field.

🔹 Data.Format.DateSeparator

When displaying and parsing Date values, this field determines the character used to separate the individual month, day, and year portions of a date.

🔹 Data.Format.DecimalSeparator

When displaying and parsing Currency or Decimal numeric values, this field determines the character used to separate the fractional part from the whole.

🔹 Data.Format.StrictDP

If the value of this field is true, then the SCE will strictly verify the number of decimal places allowed for currency input values. Thus, if the calling application sends in a request with a currency amount of 1000.005, the SCE will return an error code.

If the value of this field is false, then currency values sent in with an invalid number of decimal places will be rounded to the correct number of decimal places by the SCE (using five/four rounding), and a warning message with this information will be returned with the response.

🔹 Data.Format.ThousandSeparator

When displaying numeric values, this field determines the character used to separate the thousands places from the hundreds. Note that when parsing numeric values, the value of this field is ignored.

🟥 Data.Lien

This object itself contains no data. Instead, all of the information used to determine the type of lien is contained in the following fields of the object:

Fields: 🔹IsManufactured, 🔹LienType

Objects: None

🔹 Data.Lien.IsManufactured

This optional boolean field flags whether or not the loan is secured by a manufactured home. This field is only relevant to first liens.

🔹 Data.Lien.LienType

This optional field determines whether or not the lien is a first or subordinate lien.

🟥 Data.LoanData

This object itself contains no data. All of the loan data necessary to assess qualified mortgage status is contained in the following fields of the object:

Fields: 🔸Apr, 🔸LoanAmount, 🔸LockInYear, 🔸TermInYears

Objects: None

🔸 Data.LoanData.Apr

This required decimal field contains the Apr used for QM assessment. Three cases exist:

1.Loans with a constant interest rate use the loan's FedBox Regulation Z APR as the value of the Apr.

2.Loans whose interest rate may or will change within the first five years following the first scheduled regular payment date must compute the Apr as the Regulation Z Apr for an equivalent loan with a constant interest rate equal to the maximum interest rate occuring within the range of consideration.

e.g. A 5/1 30-year ARM loan with 45 days to the first payment must use the Fedbox Regulation Z Apr for an equivalent loan. If 9% were the maximum interest rate in the term of consideration, the equivalent loan must be computed using this 9% rate as the sole interest rate for the entire 30 years of the loan. The Regulation Z Apr for this equivalent loan is the value used in the Apr field.

3.Loans whose interest rate may or will change but only beyond the term of consideration (explained above) use the actual loan's Fedbox Regulation Z APR as the value of the Apr.

e.g. A 7/1 ARM loan would use its own FedBox RegZAPR value because the interest rate is fixed for the first seven years, thereby showing a constant interest rate within the range of consideration.

See §1026.43(e)(2)(vi) and the subsequent official interpretation for more on this critical APR determination.

🔸 Data.LoanData.LoanAmount

This required decimal field holds the value of the Loan Amount, also called the amount earning interest or the initial principal balance.

🔸 Data.LoanData.LockInYear

This required integer field holds the value of the year for the lock-in date used in the Hcm calculation.

🔸 Data.LoanData.TermInYears

This required decimal field holds the value of the number of years in the term of the loan.

🟥 Data.LoanFeatures

This object itself contains no data. All of the properties of the loan necessary to assess qualified mortgage status are contained in the following fields of the object:

Fields: 🔹HasBalloon, 🔹HasDeferredPrincipal, 🔹HasNegativeAm

Objects: None

🔹 Data.LoanFeatures.HasBalloon

This optional field signals whether or not the loan has a balloon payment (per §1026.18(s)(5)(i)) anywhere in the repayment stream. If a balloon payment exists in the repayment stream, set this optional field to true.

🔹 Data.LoanFeatures.HasDeferredPrincipal

This optional field signals whether or not the loan in question defers principal repayment. Loans which defer principal repayment are not assessed as qualified mortgages as explained in Section §1026.43(e)(2)(i)(B).

🔹 Data.LoanFeatures.HasNegativeAm

This optional field flags whether or not the loan has any negative amortization events during the repayment of the loan. If so the FeaturesTrigger becomes true. See §1026.43(e)(2)(i)(A) for more information.

🟥 Data.HcmResults

This object itself contains no data. All of the field values for this object need to be retrieved from the HCM Response associated with this loan.

Fields: 🔸Apor, 🔸TotalLoanAmount, 🔸TotalPointsFees

Objects: None

🔸 Data.HcmResults.Apor

The value of this required decimal object represents the Apor returned as the output of the Hcm calculation.

🔸 Data.HcmResults.TotalLoanAmount

This required decimal field holds the value of the TotalLoanAmount returned as part of the output of the Hcm calculation.

🔸 Data.HcmResults.TotalPointsFees

This required decimal field holds the value of the TotalPointsFees returned as part of the output of the Hcm calculation.

🟦 Data.SmallCreditorBalloon

This object itself contains no data. All of the additional features for a small creditor balloon are contained in the fields of the object that follows. Refer to §1026.43(e)(6) for more information on small creditor balloons.

Fields: 🔹HasRateIncrease, 🔸AmortTermInYears

Objects: None

🔹 Data.SmallCreditorBalloon.HasRateIncrease

This optional boolean field flags whether or not the loan has an increase to its interest rate over the term of the loan.

🔸 Data.SmallCreditorBalloon.AmortTermInYears

This required decimal field holds the value of the number of years in the amortization term of the loan.