Qualified Mortgages - Request

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

🟥 <inQM>

This is the root element of the QM request, and is required. This contains child elements which specify the particulars of the already computed loan which is being examined to see if the loan is QM compliant. The following attributes and child elements of the <inQM> element are as follows:

Attributes: 🔹DataDirPath, 🔹QmType

Elements: 🟦 <Format>, 🟥 <Lien>, 🟥 <LoanFeatures>, 🟥 <LoanData>, 🟥 <HcmResults>, 🟦 <SmallCreditorBalloon>

🔹 DataDirPath

If this attribute 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 attribute 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.

🔹 QmType

This attribute 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> element 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.

🟦 <Format>

The <Format> element is one of the first elements parsed from a request, as the attributes of this empty element affect how date and numeric values are parsed and validated.

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

Elements: None

🔹 CurrencyDecimals

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

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

🔹 DateSeparator

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

🔹 DecimalSeparator

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

🔹 StrictDP

If the value of this attribute 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 attribute 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.

🔹 ThousandSeparator

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

🟥 <Lien>

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

Attributes: 🔹IsManufactured, 🔹LienType

Elements: None

🔹 IsManufactured

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

🔹 LienType

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

🟥 <LoanData>

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

Attributes: 🔸Apr, 🔸LoanAmount, 🔸LockInYear, 🔸TermInYears

Elements: None

🔸 Apr

This required decimal attribute 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 attribute.

3. Loans whose interest rate may or will change but only beyond the term of consideration (explained in (2) 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.

🔸 LoanAmount

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

🔸 LockInYear

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

🔸 TermInYears

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

🟥 <LoanFeatures>

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

Attributes: 🔹HasBalloon, 🔹HasDeferredPrincipal, 🔹HasNegativeAm

Elements: None

🔹 HasBalloon

This optional attribute 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 attribute to true.

🔹 HasDeferredPrincipal

This optional attribute 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).

🔹 HasNegativeAm

This optional attribute 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.

🟥 <HcmResults>

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

Attributes: 🔸Apor, 🔸TotalLoanAmount, 🔸TotalPointsFees

Elements: None

🔸 Apor

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

🔸 TotalLoanAmount

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

🔸 TotalPointsFees

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

🟦 <SmallCreditorBalloon>

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

Attributes: 🔹HasRateIncrease, 🔸AmortTermInYears

Elements: None

🔹 HasRateIncrease

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

🔸 AmortTermInYears

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