Skip to main content

Search Filters & Options

This page covers how to refine your pricing search by setting loan terms, targeting specific rates, and filtering by product or program.

Setting Loan Terms​

Use termsCriteria to select the loan term in years. This field is not required, but it is preferred for tailoring results.

Single term:

"termsCriteria": [30]

Multiple terms:

"termsCriteria": [30, 20]
note

If termsCriteria is empty, Lender Price defaults to a 30 year term.

Searching for Rates​

There are several fields in the pricing search that control which rates are returned:

  • MultiCriteriaSearchModel.rate -- a single APR rate (e.g., 3.5%)
  • MultiCriteriaSearchModel.rateRange -- a range of rates with to and from values
  • Search.rates -- multiple discrete APR rates (e.g., 2%, 3%, 3.5%)
  • BrokerCriteria.rateTypes -- broad rate categories
  • BrokerCriteria.subRateTypes -- sub-categories

The most commonly used are rateRange and rateTypes.

Setting Rate Values​

Single rate: Use BrokerCriteria.rate to filter for one APR rate.

Multiple rates: Use Search.rates to search for multiple discrete APR rates.

Rate range: Use MultiCriteriaSearchModel.rateRange with to and from fields:

"rateRange": {
  "to": 2.5,
  "from": 2.6
}

This searches for all rates from 2.5 to 2.6, inclusive.

Prioritization​

If rate values are populated in multiple fields, the order of prioritization is: rateRange (highest), then rates, then rate. For example, if the request contains:

"rates": [2.5, 2.6],
"rate": 2.5

the request will search for rates at both 2.5 and 2.6.

Rate Types​

Rate types are broad categories that narrow your search. This is not required.

Rate TypeDescription
AllReturns all rate types
ForBrokerReturns the broker rate
ForCorrespondingReturns the corresponding rate
ForWholesaleReturns the wholesale rate
AsRetailReturns the retail rate

Rate types are set using BrokerCriteria.rateTypes.

Filtering by Product and Program​

The pricing search allows you to filter results by program name, product code, product name, or a combination.

Filter by Program Name​

Use filter.programName (string array). Program names must be an exact match.

Filter by Product Code​

Use filter.productCode (string array). Product codes must be an exact match and are based on the lender configuration.

Filter by Product Name​

Use filter.productName (string array).

Example​

Return results filtered for the program name "30 Year Conv" and product code "7789":

"filter": {
  "programName": ["30 Year Conv"],
  "productCode": [7789]
}

Multiple product codes and names:

"filter": {
  "productCode": [7789, 7790],
  "productName": ["Conv 30 Fixed"]
}

Filtering by Compensation​

Use brokerCriteria.minimunCompensation and brokerCriteria.maxCompensation to hide results whose points fall outside a range. A line result is only returned when its total points (adjustedPoints) is between the two values, inclusive. Results priced above maxCompensation or below minimunCompensation are not returned in the response.

FieldTypeDescription
brokerCriteria.minimunCompensationnumberLower bound, in points. Results with adjustedPoints below this value are excluded.
brokerCriteria.maxCompensationnumberUpper bound, in points. Results with adjustedPoints above this value are excluded.

Values are expressed in points (a percentage of the loan amount), so negative values represent credits. Both fields go inside brokerCriteria in the search:

"brokerCriteria": {
  "ausList": ["None", "GUS", "MUW", "LP", "DU"],
  "dayLocks": "30",
  "minimunCompensation": -1,
  "maxCompensation": 1
}

This example only returns line results priced between -1 and +1 points, and hides everything with a larger credit or a larger cost. This keeps the response focused on rates near par and can significantly reduce the response size.

Limiting Results per Rate (maxListingPerRate)​

maxListingPerRate is a root-level field of the search request that is often misunderstood. It does not limit the total number of results, and it does not limit how many rates come back -- it limits how many programs are listed under each rate.

FieldTypeDefaultDescription
maxListingPerRateinteger-1Maximum number of program line results returned per rate. -1 means unlimited.

How results are grouped​

In the pricing response, resultMap.resultRates.data is a map keyed by rate. Each key (e.g. "6.375", "6.5") holds an array of every program that qualifies at that rate:

"data": {
  "6.375": [ { "programName": "Conv 30yr A", ... }, { "programName": "Conv 30yr B", ... } ],
  "6.5":   [ { "programName": "Conv 30yr A", ... }, { "programName": "Conv 30yr B", ... }, { "programName": "Conv 30yr C", ... } ],
  "6.625": [ { "programName": "Conv 30yr A", ... } ]
}

maxListingPerRate caps the length of each of those arrays -- the best-priced programs at each rate are kept. With "maxListingPerRate": 2, the example above would still return all three rates, but the "6.5" array would be trimmed from three programs to the best two.

Choosing a value​

"maxListingPerRate": -1

Returns every qualifying program at every rate (default). Use this when you need the complete picture -- but be aware the response can get very large.

"maxListingPerRate": 1

Returns only the single best program per rate. The response reads like a rate sheet: one line per rate. This is the most common choice for summary views and integrations.

"maxListingPerRate": 3

Returns up to the 3 best programs per rate -- a middle ground when you want some program variety without the full payload.

Total result count

The number of line results in the response is roughly (number of rates) × (maxListingPerRate). If you want fewer rates rather than fewer programs per rate, use rateRange (see Searching for Rates) -- the two controls combine well.

Last updated on