> For the complete documentation index, see [llms.txt](https://api-docs.realfinity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.realfinity.io/mcp/tool-reference/pricing.md).
# Pricing
Three tools that price a mortgage scenario against OptimalBlue: one search, and two that drill into the result of that search.
{% hint style="info" %}
**These tools do not read loans, so the usual loan-scoping rule does not apply here.** What the caller's roles govern on this page is **which agent you may price as**: every call resolves a pricing agent (`userId`, defaulting to the caller) and then checks that the caller is allowed to act for that agent. Ask for an agent outside your scope and the call fails with `Unauthorized:`, not with an empty result.
{% endhint %}
**Which agents you may price as**
| You are | Agents you may price as |
| ------------ | ---------------------------------------------------------- |
| Admin | Any enabled user |
| An Assistant | Yourself, plus the agents you are bound to as an assistant |
| ConciergeKey | Yourself, plus the agents you manage |
| Anyone else | Yourself only |
{% hint style="warning" %}
**A Processor role does not widen this.** Unlike the loan tools — where a Processor reaches all loans org-wide for per-loan access, and their own company's users for the aggregate and reporting tools — the pricing-agent check is a per-user access check with no Processor branch at all. A Processor asking to price as an arbitrary colleague is rejected with `Unauthorized: You do not have access to the requested pricing agent.` Omit `userId` to price as yourself.
{% endhint %}
On top of that, the resolved pricing agent must hold a currently valid license in the property state — see `search_pricing` below.
## Call them in this order
{% hint style="warning" %}
**`get_product_details` and `get_ineligible_products` cannot be called on their own.** Both require a `searchId`, and the only place a `searchId` comes from is the response of a `search_pricing` call. There is no way to construct, look up, or reuse one from elsewhere.
{% endhint %}
```
1. search_pricing -> returns searchId + eligible products (each with productId)
2a. get_product_details -> searchId + productId + loanAmount + loanTermInYears
2b. get_ineligible_products -> searchId
```
A `searchId` is a **transient OptimalBlue session token**, not a durable record id. It expires. When either downstream tool reports a session-expired error, the fix is always the same: run `search_pricing` again with the same criteria and use the fresh `searchId`. Do not cache one across a long-running conversation.
Reach for `get_ineligible_products` only when a search returned no — or implausibly few — eligible products, or when someone explicitly asks *why* a product was rejected. It is not a routine follow-up to a successful search.
## Enum values are sent to OptimalBlue in wire format
Every enum-valued request field is accepted as a **string**, and the server translates it to the OptimalBlue wire value before the upstream call. For the enums documented on this page the wire value happens to be identical to the name shown in the tables below, so send the name exactly as written — `RefiRateTermLimitedCO`, `USDARuralHousing`, `PersonalBankStmt12Mos`. Casing matters. An unrecognized value is rejected as `Bad request:` rather than silently ignored.
Array-valued enum fields (`productTypes`, `amortizationTypes`, `loanTerms`, `armFixedTerms`) take a JSON array of those same strings.
Response field names are camel-cased throughout — `searchId`, `productId`, `lockPeriod`, `lenderFeeTotal`.
***
### search\_pricing
Search mortgage pricing and return eligible products with rates and pricing adjustments. Loan amount (or property value, which drives LTV) and state/county affect results most. If no eligible products come back, follow up with `get_ineligible_products` using the same `searchId`.
* **Backing store:** OptimalBlue, live — every call is a real request to the pricing engine
* **Roles:** Admin, Processor, DualLicensedAgent, ConciergeKey, Agent
**Every parameter has a default.** This tool is designed to be called with only the fields the user actually supplied; the rest fill in from the defaults in the tables below. The composite default is a 780-FICO, $1,125,000 loan against a $1,500,000 single-family primary residence in Miami-Dade County, Florida — a 30-year fixed conventional purchase.
Two access checks run before the search:
1. **Pricing-agent access.** The caller must be allowed to act for the resolved `userId`.
2. **State licensing.** The pricing agent must hold a license that is currently valid in the property state, or the call fails with `Unauthorized:`. A missing or unrecognizable `state` fails as `Bad request:`. This licensing check is skipped for calls originating from Realfinity's own AI chat API, because those are informational rate quotes in a public embed.
If the pricing agent has a max fee and target price configured, returned APRs include that agent's adjusted-pricing calculation alongside the original.
#### Top-level parameters
| Name | Type | Required | Description |
| --------------------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | GUID | Optional | Realfinity user ID of the pricing agent, from `search_users` or the loan's officer. **Defaults to the calling user** — resolved from the caller's own identity claim — so omit it unless you are deliberately pricing as somebody else. |
| `includeGuidelines` | boolean | Optional (default `false`) | If true, include per-product eligibility guidelines. |
| `commissionTier` | enum | Optional | LO commission tier selecting the OptimalBlue account to price under. Honored only for Realfinity AI-chat callers. Leave null to use the agent's configured account. |
| `useAgentObAccount` | boolean | Optional (default `false`) | If true, price under the agent's own OptimalBlue account (their configured channel and originator) instead of a commission-tier account. Honored only for Realfinity AI-chat callers; takes precedence over `commissionTier`. Fails if the agent has no OptimalBlue account configured. |
| `borrowerInformation` | object | Optional | Borrower-side pricing criteria. Defaults apply per field. |
| `propertyInformation` | object | Optional | Property-side pricing criteria. Defaults apply per field. |
| `loanInformation` | object | Optional | Loan-side pricing criteria. Defaults apply per field. |
| `qmInformation` | object | Optional | QM points-and-fees breakdown for APOR calculations. Leave null to treat all itemized fees as 0. |
`commissionTier` and `useAgentObAccount` are inert for ordinary MCP integrators — they are honored only for requests originating inside Realfinity's AI chat API and ignored for everyone else. You can leave both out.
#### `borrowerInformation`
| Name | Type | Required | Description |
| -------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------ |
| `citizenship` | enum | Optional (default `USCitizen`) | Borrower citizenship status. |
| `ficoScore` | integer | Optional (default `780`) | Representative FICO score (300-850). |
| `firstTimeHomeBuyer` | boolean | Optional (default `false`) | Set true on purchases to surface FTHB products and reduced MIP. |
| `selfEmployed` | boolean | Optional (default `false`) | True if the borrower is self-employed. |
| `monthsReserves` | integer | Optional (default `12`) | Months of post-closing reserves. |
| `typeOfVeteran` | enum | Optional | Required for VA loans; ignored otherwise. `ActiveDuty` or `NationalGuardOrReserves`. |
| `vaFirstTimeUse` | boolean | Optional (default `false`) | VA only. First use of VA entitlement (affects funding fee). |
| `waiveEscrows` | boolean | Optional (default `false`) | Whether escrows are waived. |
| `state` | string | Optional | Borrower mailing-address state (two-letter code), distinct from the property state. |
| `firstName` | string | Optional | Borrower first name; not used for eligibility. |
| `lastName` | string | Optional | Borrower last name; not used for eligibility. |
`firstName`, `lastName`, and `state` here are pass-through only — they change nothing about which products are returned. Leave them out unless you have a reason to carry them.
#### `propertyInformation`
| Name | Type | Required | Description |
| ----------------------- | ------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `propertyValue` | decimal | Optional (default `1500000`) | Property value in USD. Used as both appraised value and sales price unless overridden. |
| `appraisedValue` | decimal | Optional | Appraised value in USD. Overrides `propertyValue` for refinance LTV. |
| `salesPrice` | decimal | Optional | Sales price in USD. Overrides `propertyValue` for purchase LTV. |
| `state` | string | Optional (default `FL`) | Property state (two-letter US code). Drives the licensing check and product eligibility. |
| `county` | string | Optional (default `Miami-Dade`) | Property county — must match the state. Required for pricing eligibility. |
| `zipCode` | string | Optional (default `33135`) | Property ZIP code. |
| `propertyType` | enum | Optional (default `SingleFamily`) | Property type. |
| `occupancy` | enum | Optional (default `PrimaryResidence`) | Occupancy type. |
| `numberOfUnits` | enum | Optional (default `OneUnit`) | Number of dwelling units. |
| `corporateRelocation` | boolean | Optional (default `false`) | True if the borrower is being relocated by their employer. |
| `numberOfStories` | integer | Optional (default `1`) | Number of stories. |
| `propertyStreetAddress` | string | Optional | Street address; not used for eligibility. |
| `city` | string | Optional | City; not used for eligibility. |
Getting `state` and `county` right matters more than almost anything else here — county drives conforming limits and therefore which products are eligible at all. A county that does not belong to the given state will not price correctly.
#### `loanInformation`
**Loan shape**
| Name | Type | Required | Description |
| ---------------------- | ------- | ---------------------------------- | ------------------------------------------------------------------------------------ |
| `loanType` | enum | Optional (default `Conventional`) | Loan type. Drives the product set. |
| `loanPurpose` | enum | Optional (default `Purchase`) | Loan purpose. |
| `loanAmount` | decimal | Optional (default `1125000`) | Base loan amount in USD, excluding financed fees and MIP. |
| `lienType` | enum | Optional (default `First`) | Lien position: `First` or `Second`. |
| `firstLienAmount` | decimal | Optional | First-lien amount in USD when `lienType=Second` (drives CLTV). Leave null otherwise. |
| `secondLienAmount` | decimal | Optional (default `0`) | Second lien amount in USD. Affects CLTV. |
| `cashOutAmount` | decimal | Optional (default `0`) | Cash-out amount in USD (refinance). |
| `helocDrawnAmount` | decimal | Optional (default `0`) | HELOC drawn amount in USD. |
| `helocLineAmount` | decimal | Optional (default `0`) | HELOC line (limit) amount in USD. |
| `interestOnly` | boolean | Optional (default `false`) | Include interest-only products. |
| `constructionLoanType` | enum | Optional (default `NotApplicable`) | Construction loan type. |
**Product selection**
| Name | Type | Required | Description |
| ------------------- | ---------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `productTypes` | enum array | Optional (default `["StandardProducts"]`) | Product categories to include. Most scenarios use `["StandardProducts"]`; non-QM uses `["ExpandedGuidelines"]`. |
| `amortizationTypes` | enum array | Optional (default `["Fixed"]`) | Amortization types. Conventional typically `["Fixed","ARM"]`; FHA/VA/USDA typically `["Fixed"]`. |
| `loanTerms` | enum array | Optional (default `["ThirtyYear"]`) | Loan terms to include. |
| `armFixedTerms` | enum array | Conditional | **Required when `amortizationTypes` contains `ARM`**; defaults to `["FiveYear","SevenYear","TenYear"]` in that case. Ignored otherwise. |
**Pricing targets**
| Name | Type | Required | Description |
| ------------------- | ------- | ------------------------ | ----------------------------------------------------- |
| `desiredRate` | decimal | Optional (default `0`) | Target interest rate. `0` returns all eligible rates. |
| `desiredPrice` | decimal | Optional (default `100`) | Desired price (par = 100). |
| `desiredLockPeriod` | integer | Optional (default `30`) | Desired lock period in days. |
**Credit and qualification**
| Name | Type | Required | Description |
| ------------------------------ | ------- | ---------------------------------- | ------------------------------------------------------------ |
| `debtToIncomeRatio` | decimal | Optional (default `25`) | DTI percent (`25` = 25%). |
| `totalMonthlyQualifyingIncome` | decimal | Optional (default `0`) | Total monthly qualifying income in USD across all borrowers. |
| `propertiesFinanced` | integer | Optional (default `1`) | Number of properties the borrower already finances. |
| `automatedUnderwritingSystem` | enum | Optional (default `NotSpecified`) | AUS to score against. |
| `expandedApprovalLevel` | enum | Optional (default `NotApplicable`) | Expanded approval level (FHA). |
**Mortgage insurance, fees, and compensation**
| Name | Type | Required | Description |
| -------------------------------- | ------- | ---------------------------------- | --------------------------------------------------------------------- |
| `borrowerPaidMi` | enum | Optional (default `Yes`) | Whether the borrower pays mortgage insurance. |
| `reducedMi` | boolean | Optional (default `false`) | True for reduced-MI products (HomeReady, Home Possible). |
| `feesIn` | enum | Optional (default `No`) | `Yes` = closing costs financed into the loan; `No` = paid at closing. |
| `includeLoCompensationInPricing` | enum | Optional (default `YesLenderPaid`) | How LO compensation flows into pricing. |
| `buydown` | enum | Optional (default `None`) | Buydown structure. |
| `prepaymentPenalty` | enum | Optional (default `None`) | Prepayment penalty duration (non-QM). |
| `exemptFromVAFundingFee` | boolean | Optional (default `false`) | VA only. True for veterans with a service-connected disability. |
**Program flags**
| Name | Type | Required | Description |
| --------------------------- | ---- | ----------------------- | --------------------------------------------------- |
| `assetDepletion` | enum | Optional (default `No`) | Asset depletion income method. `Yes` / `No`. |
| `autoDebit` | enum | Optional (default `No`) | Automatic payment debit. `Yes` / `No`. |
| `employeeLoan` | enum | Optional (default `No`) | Employee / internal loan. `Yes` / `No`. |
| `communityAffordableSecond` | enum | Optional (default `No`) | Community Affordable Second attached. `Yes` / `No`. |
**Total loan amount**
| Name | Type | Required | Description |
| -------------------------- | ------- | ------------------------- | ----------------------------------------------------------------------------------- |
| `calculateTotalLoanAmount` | boolean | Optional (default `true`) | Auto-calculate the total loan amount. When false, `totalLoanAmountDetails` applies. |
| `totalLoanAmountDetails` | object | Optional | Total-loan override. **Only honored when `calculateTotalLoanAmount` is false.** |
**Nested objects**
| Name | Type | Required | Description |
| -------------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `expandedGuidelines` | object | Optional | Non-QM / Expanded Guidelines eligibility criteria. Defaults apply per field. |
#### `loanInformation.totalLoanAmountDetails`
| Name | Type | Required | Description |
| --------------------------------- | ------ | ---------------------- | ----------------------------------------------------------------- |
| `totalLoanAmount` | double | Optional (default `0`) | Explicit total loan amount in USD. |
| `upfrontPmiMipFfGfPercent` | double | Optional (default `0`) | Upfront PMI/MIP/FF/GF percent. |
| `upfrontPmiMipFfGfAmount` | double | Optional (default `0`) | Upfront PMI/MIP/FF/GF amount in USD (alternative to the percent). |
| `upfrontPmiMipFfGfPaidinCash` | double | Optional (default `0`) | Portion paid in cash at closing. |
| `upfrontPmiMipFfGfFinancedAmount` | double | Optional (default `0`) | Portion financed into the loan. |
#### `loanInformation.expandedGuidelines`
Only relevant when `productTypes` includes `ExpandedGuidelines` (non-QM). Otherwise the defaults are correct and you can omit the whole object.
| Name | Type | Required | Description |
| -------------------------------- | ------- | ---------------------------------- | ------------------------------------------------------ |
| `incomeVerificationType` | enum | Optional (default `FullDoc`) | Income documentation type. |
| `housingEventType` | enum | Optional (default `None`) | Recent housing event. `None` when nothing to disclose. |
| `housingEventSeasoning` | enum | Optional (default `NotApplicable`) | Required when `housingEventType` is not `None`. |
| `bankruptcyType` | enum | Optional (default `None`) | Bankruptcy chapter, if any. |
| `bankruptcyOutcome` | enum | Optional (default `NotApplicable`) | `NotApplicable` when `bankruptcyType` is `None`. |
| `bankruptcySeasoning` | enum | Optional (default `NotApplicable`) | Required when `bankruptcyType` is not `None`. |
| `debtServiceCoverageRatio` | double | Optional (default `0`) | DSCR for investor / non-QM products. |
| `uniqueProperty` | boolean | Optional (default `false`) | Unique property flag. |
| `debtConsolidation` | boolean | Optional (default `false`) | Debt consolidation flag. |
| `mortgageLates30In12Months` | integer | Optional (default `0`) | 30-day mortgage lates, last 12 months. |
| `mortgageLates30In13To24Months` | integer | Optional (default `0`) | 30-day mortgage lates, months 13-24. |
| `mortgageLates60In12Months` | integer | Optional (default `0`) | 60-day mortgage lates, last 12 months. |
| `mortgageLates60In13To24Months` | integer | Optional (default `0`) | 60-day mortgage lates, months 13-24. |
| `mortgageLates90In12Months` | integer | Optional (default `0`) | 90-day mortgage lates, last 12 months. |
| `mortgageLates90In13To24Months` | integer | Optional (default `0`) | 90-day mortgage lates, months 13-24. |
| `mortgageLates120In12Months` | integer | Optional (default `0`) | 120-day mortgage lates, last 12 months. |
| `mortgageLates120In13To24Months` | integer | Optional (default `0`) | 120-day mortgage lates, months 13-24. |
#### `qmInformation`
Optional throughout. Leave the whole object out and every fee below is treated as `0`.
| Name | Type | Required | Description |
| ------------------------------ | ------- | -------------------------- | ------------------------------------------------------------- |
| `refinancePrepaymentFeeAmount` | double | Optional (default `0`) | Refinance prepayment fee in USD. |
| `creditInsuranceFeeAmount` | double | Optional (default `0`) | Credit insurance fee in USD. |
| `cashIncentiveDiscountAmount` | double | Optional (default `0`) | Cash incentive / discount applied at closing in USD. |
| `escrowTrusteeFeeAmount` | double | Optional (default `0`) | Escrow / trustee fee in USD. |
| `propertyAssessmentFeeAmount` | double | Optional (default `0`) | Property assessment fee in USD. |
| `notaryCreditReportFeeAmount` | double | Optional (default `0`) | Notary / credit report fee in USD. |
| `documentPreparationFeeAmount` | double | Optional (default `0`) | Document preparation fee in USD. |
| `titleFeeAmount` | double | Optional (default `0`) | Title fee in USD. |
| `borrowerPaidLoCompensation` | double | Optional (default `0`) | Borrower-paid LO compensation in USD. |
| `additionalQmFeesAffectApor` | boolean | Optional (default `false`) | If true, additional QM fees count toward the APOR comparison. |
| `additionalQmFeeAmount` | double | Optional (default `0`) | Additional QM fees in USD beyond the itemized categories. |
| `financedPmi` | double | Optional (default `0`) | Financed PMI / MIP rolled into the loan, in USD. |
**Returns**
`PricingSearchResponse` — the search's identity and computed ratios, plus one entry per eligible product.
| Field | Contents |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `searchId` | **The transient OptimalBlue session token.** Pass this to `get_product_details` and `get_ineligible_products`. |
| `searchTime` | When the search ran, as returned by the engine |
| `products[]` | Eligible products — see below |
| `ltv`, `cltv`, `hcltv` | Computed loan-to-value ratios for the scenario |
| `amiPercentage` | Area median income percentage |
| `totalLoanAmountDetails` | The resolved total loan amount and upfront PMI/MIP/FF/GF breakdown |
| `guidelines[]` | Per-product eligibility guidelines — populated only when `includeGuidelines` is true |
| `messages[]` | Engine messages and advisories |
| `customerInternalId` | Upstream customer identifier |
Each entry in `products[]` is an `EligibleProduct`. The fields you will reach for most:
| Field | Contents |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `productId` | **Required by `get_product_details`.** Identifies the product within this `searchId`. |
| `productName`, `productCode`, `programName` | Product identity |
| `rate`, `price`, `apr` | Headline pricing. `originalApr`, `adjustedApr`, and `computedApr` carry the agent-adjusted variants |
| `lockPeriod` | Lock period, in days, for the quoted price |
| `principalAndInterest`, `monthlyMi`, `totalPayment` | Monthly payment components |
| `points`, `pointsCost`, `discount`, `rebate`, `closingCost`, `bonaFideDiscountPoints` | Points, credits, and costs |
| `loanType`, `loanTerm`, `amortizationType`, `amortizationTerm`, `highBalance` | Product classification |
| `armIndex`, `armIndexValue`, `armMargin`, `armFirstCap`, `armPeriodicCap`, `armLifetimeCap`, `armRelativeCap`, `armFixedTerm`, `armFixedTermMonths`, `armsubsequentChangePeriod` | ARM terms; null or zero on fixed products |
| `investor`, `investorId` | Investor behind the product |
| `qmStatus`, `priceStatus`, `pendingUpdate`, `lastUpdate` | Status and freshness |
| `loCompensationDollars`, `loCompensationPercent` | LO compensation as priced |
| `productQuote` | An embedded `ProductQuote` — the same shape `get_product_details` returns |
| `opportunityType` | Derived label pair, e.g. `{ "name": "30-Year Fixed Rate", "shortName": "Fixed30Year" }` |
No example response is published for this tool. Running `search_pricing` means placing a live request against the OptimalBlue pricing engine on behalf of a real licensed agent, so no example was captured against a live environment for this page. Every rate, price, and adjustment in a captured response would also be stale within hours of publication and actively misleading to read as a quote. Read the shape from the field tables above; `get_product_details` below carries an illustrative example with invented numbers.
**Notes**
* Call this before anything else on this page. Both other tools are inert without its `searchId`.
* The tool is built to be invoked immediately on a pricing request rather than after a round of clarifying questions — the defaults exist precisely so that a partially specified scenario still prices.
* Loan amount, property value (via LTV), and state/county move results more than any other input.
* A `Bad request:` mentioning the property state means the state was missing or unrecognizable; an `Unauthorized:` mentioning licensing means the agent is not licensed there, or the license has lapsed.
* Zero eligible products is a normal, informative outcome — not an error. Follow it with `get_ineligible_products`.
***
### get\_product\_details
Retrieve full rate quotes, lock-period pricing, an adjustments summary, and lender fee totals for one specific product from a prior `search_pricing` call.
* **Backing store:** OptimalBlue, live — resolved against the `searchId` session
* **Roles:** Admin, Processor, DualLicensedAgent, ConciergeKey, Agent
{% hint style="warning" %}
**Requires a `searchId` and a `productId` from `search_pricing`.** Both come from the same search response — the `productId` is only meaningful within the `searchId` that produced it. Do not pair a `productId` with a `searchId` from a different search.
{% endhint %}
**Parameters**
| Name | Type | Required | Description |
| ------------------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searchId` | string | **Required** | The `searchId` returned by a prior `search_pricing` call. This is a transient OptimalBlue session token — if expired, call `search_pricing` again to get a fresh one. |
| `productId` | string | **Required** | The `productId` of a specific product returned by `search_pricing`. |
| `loanAmount` | decimal | **Required** | The base loan amount in USD that quotes should be computed against. Usually matches the `loanAmount` passed to `search_pricing`. |
| `loanTermInYears` | integer | **Required** | Loan term in years (e.g. `30`, `15`, `20`). Note: a plain number of years, **not** the `loanTerms` enum used by `search_pricing`. |
| `userId` | GUID | Optional | Realfinity user ID of the pricing agent. **Defaults to the calling user.** Pass the same value used for `search_pricing`. |
| `commissionTier` | enum | Optional | Commission tier selecting the OptimalBlue account to price under. Honored only for Realfinity AI-chat callers. Use the same tier passed to `search_pricing`. |
| `useAgentObAccount` | boolean | Optional (default `false`) | Price under the agent's own OptimalBlue account instead of a commission-tier account. Honored only for Realfinity AI-chat callers; takes precedence over `commissionTier`. Use the same value passed to `search_pricing`. |
`loanTermInYears` is the parameter most often gotten wrong: `search_pricing` speaks in `loanTerms: ["ThirtyYear"]`, this tool wants `loanTermInYears: 30`.
**Returns**
`ProductQuote` — everything priced for that one product. Three things a caller comes here for:
1. **The lock-period ladder.** `quotes[]` holds one entry per rate/lock-period combination the investor offers, each with its own `rate`, `lockPeriod`, `lockExpirationDate`, `price`, `apr`, `principalAndInterest`, `monthlyMi`, `totalPayment`, `points`, `pointsCost`, `discountDollar`/`discountPercent`, `rebateDollar`/`rebatePercent`, `closingCost`, `totalCredit`, and `loCompensationDollar`/`loCompensationPercent`. `parQuotes[]` gives the par reference points (`parRate`, `parPrice`, `parLock`) the ladder is measured against.
2. **The adjustments.** `adjustments[]` is the itemized list of what moved pricing away from par: each entry carries a `reason`, an `adjustor` amount, and a `type`. `totalRateAdjustment`, `totalPriceAdjustment`, `totalSRPAdjustment`, and `totalMarginAdjustment` are the roll-ups.
3. **The lender fees.** `lenderFeeDetails[]` itemizes each fee — `feeDescription`, `feeType`, `feeTotalCalculatedAmount`, `feeTotalAmountPercent`, `feeSpecifiedFixedAmount`, `feePaidBy`, `feePaidTo`, `feePercentageBasedOn`, `feePaymentFinancedIndicator`, `prepaidFinanceChargeIndicator`, `includedInQMPointsAndFeesTest`, `rebatePriority`, `feeDetailNumber`. `lenderFeeTotal` is the computed sum of every `feeTotalCalculatedAmount`.
Alongside those: `productName`, `productId`, `searchId`, `notesAndAdvisories[]`, `originationFees`, `investorId`, `miRequiredOver80Ltv`, `interestOnlyTerm`, `constructionTermMonths`, and the ARM descriptors (`armIndex`, `armIndexValue`, `armFirstCap`, `armPeriodicCap`, `armLifetimeCap`, `armRelativeCap`, `armFixedTerm`, `armFixedTermMonths`, `armSubsequentChangePeriod`).
Example response — illustrative shape only
Field names and structure are taken from the `ProductQuote` response type. **Every number below is invented** to show the shape; none of it is a real quote, and rates like these are not being offered.
```json
{
"productName": "30 Year Fixed Conforming",
"searchId": "00000000-0000-0000-0000-000000000000",
"productId": "12345",
"parQuotes": [
{ "parRate": 6.5, "parPrice": 100.0, "parLock": 30 }
],
"quotes": [
{
"rate": 6.375,
"lockPeriod": 30,
"price": 99.25,
"apr": 6.512,
"points": 0.75,
"pointsCost": 8437.5,
"principalAndInterest": 7018.42,
"monthlyMi": 0.0,
"totalPayment": 7018.42,
"closingCost": 8437.5,
"totalCredit": 0.0,
"loCompensationPercent": 1.0
},
{
"rate": 6.5,
"lockPeriod": 30,
"price": 100.0,
"apr": 6.554,
"points": 0.0,
"pointsCost": 0.0,
"principalAndInterest": 7112.09,
"monthlyMi": 0.0,
"totalPayment": 7112.09,
"closingCost": 0.0,
"totalCredit": 0.0,
"loCompensationPercent": 1.0
},
{
"rate": 6.5,
"lockPeriod": 45,
"price": 99.875,
"apr": 6.561,
"points": 0.125,
"pointsCost": 1406.25,
"principalAndInterest": 7112.09,
"monthlyMi": 0.0,
"totalPayment": 7112.09,
"closingCost": 1406.25,
"totalCredit": 0.0,
"loCompensationPercent": 1.0
}
],
"adjustments": [
{ "reason": "FICO / LTV", "adjustor": -0.25, "type": "Price" },
{ "reason": "Lock period 45 days", "adjustor": -0.125, "type": "Price" }
],
"totalPriceAdjustment": -0.375,
"totalRateAdjustment": 0.0,
"lenderFeeDetails": [
{
"feeDetailNumber": 1,
"feeDescription": "Underwriting Fee",
"feeType": "Underwriting",
"feeSpecifiedFixedAmount": 995.0,
"feeTotalAmountPercent": 0.0,
"feeTotalCalculatedAmount": 995.0,
"feePaidBy": "Borrower",
"feePaymentFinancedIndicator": false,
"prepaidFinanceChargeIndicator": true,
"includedInQMPointsAndFeesTest": true
}
],
"lenderFeeTotal": 995.0,
"notesAndAdvisories": [
"Escrow waiver subject to investor overlay."
],
"armFixedTerm": null,
"armFixedTermMonths": null,
"miRequiredOver80Ltv": true
}
```
**Notes**
* The `productId` is scoped to its `searchId`. Reusing an old `productId` against a new search will not reliably resolve to the same product.
* A session-expired error means the `searchId` aged out. Re-run `search_pricing`; there is no refresh call.
* `search_pricing` already embeds a `productQuote` per eligible product. Call this tool when you need the full lock-period ladder, adjustment itemization, and fee detail for one product rather than the summary.
* Pass the same `userId` (and, for AI-chat callers, the same `commissionTier` / `useAgentObAccount`) used for the search. Mismatched account selection prices under a different OptimalBlue account.
***
### get\_ineligible\_products
List the mortgage products that were **ineligible** for a prior `search_pricing` call, grouped by product type (e.g. "15 Year Fixed Conforming"). Each product shows only its name and the reason or reasons it was rejected — LTV, DTI, loan-amount, and state limits being the usual culprits.
* **Backing store:** OptimalBlue, live — resolved against the `searchId` session
* **Roles:** Admin, Processor, DualLicensedAgent, ConciergeKey, Agent
{% hint style="warning" %}
**Requires a `searchId` from `search_pricing`.** There is no other source for one.
{% endhint %}
**Parameters**
| Name | Type | Required | Description |
| ------------------- | ------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searchId` | string | **Required** | The `searchId` returned by a prior `search_pricing` call. Transient OptimalBlue session token — if expired, call `search_pricing` again to get a fresh one. |
| `includeAll` | boolean | Optional (default `false`) | By default each product type returns at most **50** products (`totalProducts` still reports the full count, and `truncated` flags that more exist). Set to true to return **all** ineligible products in every type. Token-intensive — only use it when the default results are insufficient to explain the ineligibility. |
| `userId` | GUID | Optional | Realfinity user ID of the pricing agent. **Defaults to the calling user.** Pass the same value used for `search_pricing`. |
| `commissionTier` | enum | Optional | Commission tier selecting the OptimalBlue account to price under. Honored only for Realfinity AI-chat callers. Use the same tier passed to `search_pricing`. |
| `useAgentObAccount` | boolean | Optional (default `false`) | Price under the agent's own OptimalBlue account instead of a commission-tier account. Honored only for Realfinity AI-chat callers; takes precedence over `commissionTier`. Use the same value passed to `search_pricing`. |
**Returns**
`IneligibleProductsResult` — a deliberately token-lean, grouped shape that mirrors the Realfinity UI's "Ineligible" view. Products are grouped by term / amortization type / loan type, and each product keeps only its name and rejection reasons. Every other OptimalBlue product field is dropped to keep the response small, and per-product guidelines are never requested upstream.
| Field | Contents |
| ----------------------------------------------- | -------------------------------------------------------------------------------- |
| `searchId` | The search this result belongs to |
| `totalProducts` | Total ineligible products found, regardless of how many are returned |
| `returnedProducts` | How many were actually included across all groups |
| `truncated` | True when products were capped — call again with `includeAll: true` for the rest |
| `productTypes[]` | The groups: each has a `productType` label and a `products[]` array |
| `productTypes[].products[].productName` | Product name |
| `productTypes[].products[].ineligibleReasons[]` | Why it was rejected |
Example response — illustrative shape only
Field names and structure are taken from the `IneligibleProductsResult` response type. Product names and reason text are **invented** for illustration.
```json
{
"searchId": "00000000-0000-0000-0000-000000000000",
"totalProducts": 214,
"returnedProducts": 100,
"truncated": true,
"productTypes": [
{
"productType": "15 Year Fixed Conforming",
"products": [
{
"productName": "Example Investor 15 Yr Fixed",
"ineligibleReasons": [
"Loan amount exceeds maximum for this product",
"LTV exceeds 80% maximum"
]
}
]
},
{
"productType": "30 Year Fixed Non-Conforming",
"products": [
{
"productName": "Example Investor Jumbo 30 Yr Fixed",
"ineligibleReasons": [
"DTI exceeds 43% maximum"
]
}
]
}
]
}
```
**Notes**
* Call this only when a search returned no — or very few — eligible products, or when someone asks explicitly which products were ineligible and why. It is not a routine follow-up.
* Check `truncated` before concluding you have seen everything. `totalProducts` is the honest count; `returnedProducts` is what you got.
* Reach for `includeAll: true` sparingly. A full non-QM search can return hundreds of ineligible products, and the response gets large fast.
* The same reason often repeats across an entire product type. Reading one representative product per group usually answers "why did nothing price?" without expanding the cap.
***
## Enum reference
Accepted values, exactly as they should be sent. These are also the OptimalBlue wire values.
| Field | Accepted values |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loanInformation.loanType` | `Conforming`, `NonConforming`, `FHA`, `VA`, `Conventional`, `HELOC`, `USDARuralHousing` |
| `loanInformation.loanPurpose` | `Purchase`, `RefiCashout`, `RefiRateTermLimitedCO`, `FHAStreamlineRefi`, `VARateReduction`, `SimpleRefinance` |
| `loanInformation.lienType` | `First`, `Second` |
| `loanInformation.productTypes[]` | `StandardProducts`, `AffordableProducts`, `HARP`, `HeroProducts`, `StudentLoanCORefi`, `RenovationAndRehabilitation`, `BondAndHFA`, `HUDspecialty`, `USDAStreamline`, `ExpandedGuidelines` |
| `loanInformation.amortizationTypes[]` | `Fixed`, `ARM`, `Balloon`, `OptionArm` |
| `loanInformation.loanTerms[]` | `ThirtyYear`, `TwentyFiveYear`, `TwentyYear`, `FifteenYear`, `TenYear`, `NineYear`, `EightYear`, `SevenYear`, `SixYear`, `FiveYear`, `FourYear`, `ThreeYear`, `TwoYear`, `OneYear`, `TwelveYear`, `FortyYear`, `NineMonth`, `SixMonth`, `ThreeMonth`, `NonStandardTerm` |
| `loanInformation.armFixedTerms[]` | `OneMonth`, `ThreeMonth`, `SixMonth`, `OneYear`, `TwoYear`, `ThreeYear`, `FiveYear`, `SixYear`, `SevenYear`, `TenYear`, `FifteenYear` |
| `loanInformation.automatedUnderwritingSystem` | `DU`, `LP`, `NotSpecified`, `InvestorAUS`, `ManualTraditional` |
| `loanInformation.borrowerPaidMi` | `Yes`, `No` |
| `loanInformation.buydown` | `None`, `ThreeTwoOne`, `TwoOne`, `OneZero`, `OneOne` |
| `loanInformation.feesIn` | `No`, `Yes` |
| `loanInformation.expandedApprovalLevel` | `NotApplicable`, `LevelOne`, `LevelTwo`, `LevelThree`, `LevelFour`, `LevelFive` |
| `loanInformation.prepaymentPenalty` | `None`, `OneYear`, `TwoYear`, `ThreeYear`, `FourYear`, `FiveYear` |
| `loanInformation.includeLoCompensationInPricing` | `YesLenderPaid`, `NoBuyerPaid`, `NoLenderPaid` |
| `loanInformation.constructionLoanType` | `NotApplicable`, `Construction`, `ConstructionToPerm` |
| `loanInformation.assetDepletion` / `autoDebit` / `employeeLoan` / `communityAffordableSecond` | `Yes`, `No` |
| `propertyInformation.occupancy` | `PrimaryResidence`, `SecondHome`, `InvestmentProperty` |
| `propertyInformation.propertyType` | `SingleFamily`, `Condo`, `DetachedCondo`, `NonWarrantableCondo`, `Condotel`, `Townhouse`, `PUD`, `Coop`, `Modular`, `ManufacturedSingleWide`, `ManufacturedDoubleWide`, `Timeshare` |
| `propertyInformation.numberOfUnits` | `OneUnit`, `TwoUnits`, `ThreeUnits`, `FourUnits` |
| `borrowerInformation.citizenship` | `USCitizen`, `USCitizenAbroad`, `PermResidentAlien`, `NonPermResidentAlien`, `ForeignNational` |
| `borrowerInformation.typeOfVeteran` | `ActiveDuty`, `NationalGuardOrReserves` |
| `expandedGuidelines.incomeVerificationType` | `FullDoc`, `OneYearAltDoc`, `TwoYearAltDoc`, `WrittenVOE`, `Stated`, `NoIncomeVerification`, `AssetRelated`, `RestrictedStock`, `InvestorDscr`, `InvestorNoRatio`, `OneYear1099`, `TwoYear1099`, `PLOneYear`, `PLTwoYear`, `PersonalBankStmt1Mo`, `PersonalBankStmt3Mos`, `PersonalBankStmt6Mos`, `PersonalBankStmt12Mos`, `PersonalBankStmt18Mos`, `PersonalBankStmt24Mos`, `BusinessBankStmt1Mo`, `BusinessBankStmt3Mos`, `BusinessBankStmt6Mos`, `BusinessBankStmt12Mos`, `BusinessBankStmt18Mos`, `BusinessBankStmt24Mos` |
| `expandedGuidelines.housingEventType` | `None`, `DeedInLieu`, `Foreclosure`, `Modification`, `ShortSale`, `Forbearance` |
| `expandedGuidelines.housingEventSeasoning` / `bankruptcySeasoning` | `NotApplicable`, `Last1To12Months`, `Last13To24Months`, `Last25To36Months`, `Last37To48Months`, `Last49To60Months`, `MoreThanFiveYearsAgo` |
| `expandedGuidelines.bankruptcyType` | `None`, `Chapter7`, `Chapter11`, `Chapter13` |
| `expandedGuidelines.bankruptcyOutcome` | `NotApplicable`, `Discharged`, `Dismissed`, `OpenOrPending` |
| `commissionTier` (all three tools) | `HalfPercent` (0.50%), `ThreeQuarterPercent` (0.75%), `OnePercent` (1.00%), `OneAndThreeQuarterPercent` (1.75%) |
***
## Related pages
* [Overview](/mcp/overview.md) — what the MCP server is and which tools exist
* [Authentication](/mcp/connecting/authentication.md) — connecting and obtaining a token
* [Loan Lookup](/mcp/tool-reference/loan-lookup.md) — find the loan and its officer, whose `userId` you can price as
* [Troubleshooting](/mcp/connecting/troubleshooting.md) — error labels, expired sessions, empty results