Pricing HELOC and HELOANs

The API supports two home equity products, identified by the criteria.mortgageTypes value:

Product	`criteria.mortgageTypes`	Description	Typical `loanType`
HELOC	`["HELOC"]`	Revolving home equity line of credit	`"Variable"`
HELOAN	`["HomeEquity"]`	Fixed-amount, closed-end home equity loan	`"Fixed"`

Equity products use the amount fields (loanAmount, lineAmount, drawAmount, subordinateLoanAmount) differently from standard mortgages. Getting this mapping wrong is the most common cause of missing products, wrong adjustments, and incorrect LTV calculations — so read Which Amount Goes Where first.

Price HELOCs in a separate request

HELOC cannot be combined with other mortgage types in a single pricing call. A request like "mortgageTypes": ["VA", "HELOC"] returns no HELOC products. To show HELOC results alongside other products, make two pricing calls — one with ["HELOC"], one with the other mortgage types — and combine the responses.

HELOAN (HomeEquity) does not have this restriction, but sending it alone gives the most predictable LTV/CLTV behavior.

Which Amount Goes Where

Field definitions for equity scenarios:

Field	Meaning
`criteria.loanAmount`	The loan being priced — except for HELOC, where it is the balance of the existing first lien (not the HELOC amount)
`criteria.lineAmount`	HELOC only: the total approved credit line
`criteria.drawAmount`	HELOC only: the amount drawn at closing (initial draw)
`criteria.subordinateLoanAmount`	Balance of other existing liens. For a second-lien HELOAN this is the first-lien balance ("amount owed")
`criteria.lienPriorityType`	Lien position of the loan being priced: `FirstLien`, `SecondLien`, `ThirdLien` … `SeventhLien`, `Other`

How to fill them per scenario:

Scenario	`loanAmount`	`lineAmount`	`drawAmount`	`subordinateLoanAmount`
HELOC, first lien	`0`	Total credit line	Initial draw	`0`
HELOC, second lien (existing first mortgage)	Existing first-lien balance	Total credit line	Initial draw	`0`
HELOAN (or any non-HELOC), second lien	Amount needed (the new loan)	`0`	`0`	Amount owed (existing first-lien balance)
First mortgage with a subordinate HELOC (piggyback)	The new first mortgage	HELOC total line	HELOC drawn amount	Other closed-end junior liens, else `0` — and set `criteria.subordinateSubType: "HELOC"`

The classic mistake

For a second-lien HELOC, do not put the HELOC amount in loanAmount or the first-lien balance in subordinateLoanAmount. A borrower with a $300,000 first mortgage opening a $250,400 line, fully drawn, on a $1,000,000 home is:

"appraisedValue": 1000000,
"loanAmount": 300000,
"lineAmount": 250400,
"drawAmount": 250400,
"subordinateLoanAmount": 0

Swapping loanAmount/drawAmount, or duplicating the first lien into subordinateLoanAmount, inflates HCLTV and triggers price adjustments (or disqualifications) that don't apply to the real scenario.

Pricing a HELOC

Key request settings:

Setting	Value	Notes
`criteria.mortgageTypes`	`["HELOC"]`	Alone — never mixed with other types
`criteria.loanType` / `loanTypeCriteria`	Usually `"Variable"`	Must match how the lender's HELOC products are configured. Fixed-rate HELOCs exist — if you get no results with `Variable`, also try `Fixed`
`varLoanTypeCriteria`	One value, matching the lender's HELOC product setup	For Variable HELOCs. HELOC rates are not true ARMs (they can change with the index at any time), so lenders configure a placeholder reset period on the product — commonly `_1m_1m` (monthly), but some use other values such as `_10_1`. The value you send must match the product's configuration; a mismatch (or omitting the field) disqualifies products with reason `Variable type : [...] <> [...]`, and that reason text shows the configured value to send
`criteria.interestOnly`	`true` (or `null` for both)	Important: this field defaults to `false`, which only matches fully-amortizing products. Most HELOCs are interest-only during the draw period, so the default silently filters them out
`criteria.lienPriorityType`	`"SecondLien"` or `"FirstLien"`	Set it explicitly. When omitted, products still match, but lender adjustments that are restricted by lien position are silently skipped
`criteria.lineAmount` / `criteria.drawAmount`	See table above	Lenders commonly configure min/max line and draw amount rules — sending `0` can disqualify products (e.g. minimum line amount rules)
`criteria.appraisedValue`	Property value	Required (`purchasePrice` also works for purchase scenarios)
`termsCriteria`	e.g. `[30]`	The product's total term in years (e.g. a 10-year draw + 20-year repayment product is `30`). The draw/repayment split is product configuration, not a search input
VA/FHA fee fields	Remove them	`veteranType`, `vaUsageType`, `ufmipFinanced`, `fundingFeeFinanced`, `guranteeFeeFinanced` belong to VA/FHA requests, not HELOC

How LTV is calculated for HELOC

Ratio	Second-lien HELOC	First-lien HELOC
LTV	`lineAmount ÷ value`	`drawAmount ÷ value`
CLTV	`(loanAmount + drawAmount + subordinateLoanAmount) ÷ value`	`drawAmount ÷ value`
HCLTV	`(loanAmount + lineAmount + subordinateLoanAmount) ÷ value`	`lineAmount ÷ value`

For second liens, value is min(appraisedValue, purchasePrice) on Purchase scenarios and appraisedValue on refinance scenarios.

Setting criteria.helocCriteria: { "applyLineAmount": true } makes the engine use lineAmount instead of drawAmount as the basis for first-lien HELOC LTV, APR, and payment computations (CLTV always uses drawAmount). Leave it at the default (false) unless your program guidelines qualify on the full line.

Reading HELOC results

lineResult.loanAmount in the response reflects the drawAmount, since that is the amount being priced.
The monthly payment is computed on the draw amount (typically interest-only during the draw period), not the full line.
For variable HELOCs, the returned rate is the fully indexed rate (index + margin), not a raw note rate.

Example: second-lien HELOC

A borrower with an existing $300,000 first mortgage opens a $250,400 line on their $1,000,000 primary residence and draws it fully at closing:

{
  "companyId": "65a1b2c3d4e5f60718293a4b",
  "criteria": {
    "fico": 760,
    "loanPurpose": "CashoutRefinance",
    "loanType": "Variable",
    "mortgageTypes": ["HELOC"],
    "propertyUse": "PrimaryResidence",
    "lienPriorityType": "SecondLien",
    "interestOnly": true,
    "appraisedValue": 1000000,
    "loanAmount": 300000,
    "lineAmount": 250400,
    "drawAmount": 250400,
    "subordinateLoanAmount": 0,
    "monthlyIncome": 20000,
    "monthlyDebt": 500
  },
  "property": {
    "address": { "zip": "91776", "state": "CA" },
    "propertyType": "SingleFamily",
    "numberOfUnit": 1
  },
  "termsCriteria": [30],
  "loanTypeCriteria": ["Variable"],
  "loanPurposeCriteria": ["CashoutRefinance"],
  "varLoanTypeCriteria": ["_1m_1m"]
}

For a piggyback HELOC at purchase, use "loanPurpose": "Purchase" (with loanPurposeCriteria to match) and include purchasePrice.

Pricing a HELOAN

HELOANs are standard closed-end loans, so they follow normal mortgage conventions — with one mapping rule that trips people up on second liens:

"Amount needed" → criteria.loanAmount. "Amount owed" → criteria.subordinateLoanAmount.

This applies to all mortgage types except HELOC — so HomeEquity, Conventional, and VA second liens all follow it.

Key request settings:

Setting	Value	Notes
`criteria.mortgageTypes`	`["HomeEquity"]`	Can be combined with other non-HELOC types (e.g. `["HomeEquity", "VA"]`), but sending it alone gives the most predictable ratio calculations
`criteria.loanType` / `loanTypeCriteria`	`"Fixed"`	HELOANs are fixed-rate
`criteria.loanAmount`	Amount needed	The new equity loan being priced
`criteria.subordinateLoanAmount`	Amount owed	The existing first-lien balance
`criteria.lienPriorityType`	`"SecondLien"`
`criteria.lineAmount` / `criteria.drawAmount`	`0`	HELOC-only fields
`criteria.appraisedValue`	Property value	If not sent, `purchasePrice` is used as the property value
`criteria.cashoutAmount`	Cash to borrower	For cashout scenarios; lenders can configure min/max cashout rules against it
`termsCriteria`	e.g. `[5, 10, 15, 20]`	Match the lender's HELOAN product terms

For a second-lien HELOAN, LTV reflects the existing first lien (subordinateLoanAmount ÷ value), and CLTV reflects both liens ((loanAmount + subordinateLoanAmount) ÷ value).

Example: second-lien HELOAN

A borrower who owes $320,000 on their first mortgage and needs $50,000, on a $750,000 primary residence:

{
  "companyId": "65a1b2c3d4e5f60718293a4b",
  "criteria": {
    "fico": 740,
    "loanPurpose": "CashoutRefinance",
    "loanType": "Fixed",
    "mortgageTypes": ["HomeEquity"],
    "propertyUse": "PrimaryResidence",
    "lienPriorityType": "SecondLien",
    "appraisedValue": 750000,
    "loanAmount": 50000,
    "lineAmount": 0,
    "drawAmount": 0,
    "subordinateLoanAmount": 320000,
    "monthlyIncome": 12000,
    "monthlyDebt": 800
  },
  "property": {
    "address": { "zip": "91776", "state": "CA" },
    "propertyType": "SingleFamily",
    "numberOfUnit": 1
  },
  "termsCriteria": [5, 10, 15, 20],
  "loanTypeCriteria": ["Fixed"],
  "loanPurposeCriteria": ["CashoutRefinance"],
  "varLoanTypeCriteria": []
}

Common Pitfalls

Mixed HELOC request returns nothing. "mortgageTypes": ["VA", "HELOC"] will not return HELOC products. Price HELOC in its own call.
Swapped amount fields. For HELOC: loanAmount = existing first lien, lineAmount/drawAmount = the HELOC. For HELOAN: loanAmount = amount needed, subordinateLoanAmount = amount owed. See Which Amount Goes Where.
interestOnly left at its default. The default false only matches fully-amortizing products and silently excludes interest-only HELOCs. Send true (or null to match both).
Wrong or missing varLoanTypeCriteria on a Variable HELOC. Products get disqualified with Variable type : [...] <> [...]. The expected value depends on how the lender configured the product (_1m_1m, _10_1, …) — the disqualification reason shows the value to send.
VA/FHA fee fields in a HELOC request. Remove veteranType, vaUsageType, ufmipFinanced, fundingFeeFinanced, and guranteeFeeFinanced — they belong to VA/FHA scenarios.
Missing lienPriorityType. Products still match, but lien-restricted lender adjustments are silently skipped, so pricing can be wrong rather than missing.
Zero lineAmount/drawAmount on a HELOC. Lenders configure minimum line/draw amount rules; zeros can disqualify everything. Some lenders also require drawAmount equal to lineAmount — the initial draw is the borrower's choice, subject to the lender's guidelines.
No property value. Either appraisedValue or purchasePrice must be greater than 0 or the request is rejected.
Missing lender-specific dynamic fields. Some lenders qualify equity products on dynamic fields (e.g. Citizenship, IncomeDocType) sent in dynamicPropertiesMap. See Dynamic Properties.
The product is configured under the other mortgage type. Program names don't always match the configured type — a program called "HELOC" can contain products configured as HomeEquity (and vice versa). Matching keys off the configured mortgageTypes value, not the name, so if an expected product is missing from a ["HELOC"] search, try ["HomeEquity"].

Debugging empty results

Add "showDisqualify": true at the root of the request to include disqualified products in the response along with the rule that removed each one (e.g. Loan Term : 30 (Year) <> [40] or Variable type : [...] <> [...]). That tells you exactly which field to adjust.

Which Amount Goes Where​

Pricing a HELOC​

How LTV is calculated for HELOC​

Example: second-lien HELOC​

Pricing a HELOAN​

Example: second-lien HELOAN​

Common Pitfalls​

See Also​