> For the complete documentation index, see [llms.txt](https://even-financial.gitbook.io/developer-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://even-financial.gitbook.io/developer-center/marketplace-integrations/web-embeds/mortgage-marketplace.md).

# Mortgage Marketplace

Implementation, Syntax, Consumer Experience, Tags, Tracking, and Best Practices

{% hint style="success" icon="person-waving" %}
This page outlines what's needed to integrate Engine's Mortgage Embed into your website. In this guide, we will explore what Engine's Embed syntax looks like and best practices for loading it on your site. This includes topics like proactively addressing layout shift for optimized performance.

This is a high-level guide, and specific implementation details should be discussed with your Engine team.
{% endhint %}

Engine embeds run the same backend Mortgage application as our [Hosted Partner Page](/developer-center/marketplace-integrations/partner-pages.md) do, but as opposed to linking out to a MoneyLion-hosted page they can be embedded directly into you property for a more native experience.

## The Mortgage Experience

Engine's Mortgage embed covers **purchase, refinance, and home equity (HELOC and HELOAN).** The embed renders three surfaces, and your zone configuration decides which one the consumer lands on first:

* **Explore.** A rate-trend chart built on current APR data. It shows how rates have moved rather than listing offers, so a consumer can arrive with no information and still see something useful. Its call-to-action hands off to Search.
* **Search.** The question flow that qualifies the consumer and ends by creating an offer search with Engine's lending partners.
* **Compare.** The results page for that offer search. The consumer can sort the offers, page through them, and narrow them with filters, and each offer's call-to-action sends the consumer to that lender. Compare is the last Engine screen in the flow.

**Your Engine representative will set the entrypoint per zone to either Explore or Search.** Compare is not available as an entrypoint, because the page is scoped to the offer search that Search created - the only way to reach it is to complete the question flow.

**Which filters appear on Compare depends on the mortgage type.** Purchase and refinance offers can be narrowed by loan term and by FHA and VA program eligibility. Home equity offers can be narrowed by property value, current mortgage balance, and requested loan amount.

### The Search Funnel

Mortgage asks a different opening question than Engine's other marketplaces: the consumer states a goal - buying a home, refinancing, or borrowing against home equity - and that answer changes which questions follow.

<table><thead><tr><th width="194.37890625">Step</th><th>What the consumer provides</th></tr></thead><tbody><tr><td>Mortgage Information</td><td><p><strong>Purchase:</strong> goal, plus purchase price and down payment</p><p><strong>Refinance:</strong> property value and current mortgage balance</p><p><strong>Home Equity</strong>: property value, current mortgage balance, and desired loan amount</p></td></tr><tr><td>Zip Code</td><td>The property's ZIP code</td></tr><tr><td>Cash Out</td><td><strong>Refinance only.</strong> Whether the consumer wants cash out, or a rate-and-term refinance</td></tr><tr><td>Credit Score</td><td>Self-reported credit score range</td></tr><tr><td>Identity Verification</td><td>Date of birth and phone number</td></tr><tr><td>Contact Information</td><td>First name, last name, and email</td></tr><tr><td>Personal Information</td><td>Mailing address</td></tr><tr><td>SSN and Consents</td><td>Social Security Number, with FCRA and TCPA consent</td></tr></tbody></table>

**Not every consumer may see every step.** When Engine already has consumer data because identity verification returned i, the marketplace routes past those steps instead of asking again. Identity verification may also insert an SMS one-time-passcode step.

## Standard Embed Implementation

Engine's embed code can be placed in any order within your page, but for optimal user experience we recommend placing the `script` tag within the same div where the content is being rendered.

### Embed Components

* **Channel & Zone**: placeholders that will be replaced with precise values in the embed code provided to you.
* **Component Name**: corresponds to the specific product or Engine experience type that's being rendered.
  * Mortgage is served from `/web-component/mortgage/` : the full Mortgage marketplace - Explore, Search, and Compare, across purchase, refinance, and home equity. Mortgage ships a single component rather than one per surface. It always opens the app root, and Engine's zone configuration decides whether the consumer starts on Explore or Search, so there is no `experience` attribute to set.
* **Mounting:** manual is the default. Place where the marketplace should render. The script tag and the element can appear in either order on the page.
  * With `data-embed-type="auto-mount"`, do not add the element - the script inserts the component immediately after itself when the bundle loads. In this mode the script tag must be inside , in the exact position where the marketplace should appear.

### Basic Syntax

This is a representative example of what our embed code looks like, and placeholders will be replaced with precise values in the embed code provided to you:

<pre class="language-html" data-overflow="wrap"><code class="lang-html"><strong>&#x3C;script
</strong>  async
  src="https://www.moneylion.com/network/{channel}/{zone}/web-component/mortgage/index.js"
  data-embed-type="auto-mount"
>&#x3C;/script>
</code></pre>

{% hint style="info" icon="triangle-exclamation" %}
**PLEASE NOTE**: Your Engine representative will provide you with your specific code snippet. Do not try to reproduce from the sample snippet outlined below.
{% endhint %}

### Customization & Auto Sizing

The web component loads an iFrame and will automatically fill the container. Embeds are rendered wherever you include our HTML tag on your page and will responsively scale to fill the space available to it. The embedded app reports its own height to your page as the consumer moves through the flow, so the iFrame grows and shrinks with the content.

## Required Consumer Data Inputs

The Mortgage experience collects every field below itself, inside the Search funnel. Fields appear in the order the consumer meets them, matching the Search Funnel above.

A consumer is only asked for the fields belonging to the mortgage type they picked, and any step Engine can already satisfy - through identity verification - is skipped rather than asked again.

<table><thead><tr><th width="180">Name</th><th width="202.5927734375">Field Name</th><th width="247.1923828125">Description</th><th width="160">Required? Which Mortgage Product(s)?</th></tr></thead><tbody><tr><td>Mortgage Type</td><td><code>mortgageType</code></td><td>What the consumer wants to do. <strong>Values</strong>: <code>purchase</code>, <code>refinance</code>, <code>heloc</code>. Home equity submits <code>heloc</code> and leaves the lead's <code>mortgageType</code> unset.</td><td>All Mortgage Product Types</td></tr><tr><td>Purchase Price</td><td><code>purchasePrice</code></td><td>Purchase price of the home. Stored on the lead as <code>propertyValue</code>.</td><td>Purchase only</td></tr><tr><td>Down Payment</td><td><code>downPayment</code></td><td>Cash down payment, in dollars. Stored on the lead as <code>downPaymentAmount</code>.</td><td>Purchase only</td></tr><tr><td>Down Payment Percentage</td><td><code>downPaymentPercent</code></td><td>The same down payment expressed as a percentage of purchase price. Used by the form only; not stored on the lead.</td><td>Purchase only</td></tr><tr><td>Property Value</td><td><code>propertyValue</code></td><td>Current estimated value of the home.</td><td>Refinance and Home Equity</td></tr><tr><td>Current Mortgage Balance</td><td><code>loanBalance</code> (refinance)<br><code>mortgageBalance</code> (home equity)</td><td>Outstanding balance on the existing mortgage. Stored on the lead as <code>mortgageBalance</code> in both cases.</td><td>Refinance and Home Equity</td></tr><tr><td>Desired Loan Amount</td><td><code>desiredLoanAmount</code></td><td>Amount the consumer wants to borrow against their equity. Stored on the lead as <code>mortgageAmount</code>.</td><td>Home Equity only</td></tr><tr><td>Property ZIP Code</td><td><code>zipcode</code></td><td>ZIP code of the property being financed, collected on the Zip Code step. Distinct from the consumer's mailing ZIP. Stored on the lead as <code>propertyZipcode</code>, and Engine derives <code>propertyState</code> from it.</td><td>All Mortgage Product Types</td></tr><tr><td>Cash Out</td><td><code>cashOut</code></td><td>Whether the consumer wants cash out or a rate-and-term refinance. <strong>Values</strong>: <code>yes</code>, <code>no</code>. Stored on the lead as <code>refinanceType</code> (<code>cash_out</code> or <code>rate_term</code>).</td><td>Refinance only</td></tr><tr><td>Credit Score</td><td><code>creditScoreRange</code></td><td>Self-reported credit score range. Stored on the lead as <code>mortechCreditRating</code>. Engine always runs a soft pull.</td><td>All Mortgage Product Types</td></tr><tr><td>Date of Birth</td><td><code>dateOfBirth</code></td><td>Consumer's date of birth. Stored on the lead as <code>YYYY-MM-DD</code>.</td><td>All Mortgage Product Types</td></tr><tr><td>Phone Number</td><td><code>phoneNumber</code></td><td>Primary phone number. Stored on the lead as <code>primaryPhone</code>.</td><td>All Mortgage Product Types</td></tr><tr><td>First Name</td><td><code>firstName</code></td><td>Legal first name.</td><td>All mortgage types</td></tr><tr><td>Last Name</td><td><code>lastName</code></td><td>Legal last name.</td><td>All mortgage types</td></tr><tr><td>Email Address</td><td><code>email</code></td><td>Email address.</td><td>All mortgage types</td></tr><tr><td>Street Address</td><td><code>address1</code></td><td>Mailing street address.</td><td>All mortgage types</td></tr><tr><td>Address Line 2</td><td><code>address2</code></td><td>Apartment, unit, or suite.</td><td>Optional</td></tr><tr><td>City</td><td><code>city</code></td><td>Mailing city.</td><td>All Mortgage Product Types</td></tr><tr><td>State</td><td><code>state</code></td><td>Mailing state.</td><td>All Mortgage Product Types</td></tr><tr><td>Mailing ZIP Code</td><td><code>zipcode</code></td><td>The consumer's mailing ZIP code, collected on the Personal Information step. May differ from the property ZIP.</td><td>All Mortgage Product Types</td></tr><tr><td>Social Security Number</td><td><code>ssn</code></td><td>Collected and stored in the form <code>NNN-NN-NNNN</code>.</td><td>All Mortgage Product Types</td></tr></tbody></table>

## Client Tags for Reporting & Attribution

{% hint style="warning" %}
Client tags are appended to the Mortgage marketplace URL, and the Mortgage web component does not currently accept a `tags` attribute the way some other Engine embeds do. Do not copy the `tags` or `data-tags` syntax from another product's embed page - confirm client tag attribution for your Mortgage embed with your Engine team.
{% endhint %}

Client tags let Engine attribute leads and offer clicks back to your own reporting. Where they are supported, the syntax is a `tag.` prefix on each key:

```
tag.key_1=value_1&tag.key_2=value_2
```

Client tags carried on the Mortgage marketplace URL are attached to the offer search Engine creates for that consumer, which is what makes them available in your reporting. For a URL-based integration, see [Client Tags on the Hosted Partner Page](/developer-center/marketplace-integrations/partner-pages.md).

#### Supported Client Tag Keys

{% hint style="warning" %}
Client tag keys are matched exactly, including case. For example - `subid` and `subId` are stored as separate tags and will appear as separate keys in your reporting.

Please send each key with consistent casing across all requests, and use the exact spelling shown above.
{% endhint %}

Below are the client tag keys that are currently supported:

* agentId
* campaignId
* clickId
* clientId
* deviceId
* medium
* sourceId
* subId
* subId1
* subId2
* subId3
* target
* trafficsource
* userId

If a different key is needed, please reach out to your Partner Manager - we may be able to accommodate, but adding nonstandard keys will increase the time it takes Engine to report Client Tag values back to you and is therefore not recommended.

## Tracking Events Emitted by Embed

When you embed the Mortgage experience, **event callbacks fire by default**. There is no attribute, flag, or opt-in to enable them.

### How It Works

As a consumer navigates through the experience, the embed emits **partner messages**: JSON objects with a `name` (the event type) and a `payload` (event-specific data). The iFrame posts them to your host page with `postMessage`.

* You do not register callbacks with Engine. You listen on your host page; messages arrive whether or not you handle them.
* Not every UI action sends a message. Only the events listed below are part of the partner contract. Other activity - offers rendering, offer detail views, and the embed scrolling into view - is used internally and is not posted to your page.
* Messages are one-way. There is no acknowledgement or response channel.

### Implementation Path

Partners using Web Embed receive events by listening for browser `message` events on the host page:

```js
window.addEventListener('message', (event) => {
  const message = event.data
  if (!message || typeof message !== 'object' || typeof message.name !== 'string') {
    return
  }
  console.log(message.name, message.payload)
})
```

The message shape is always:

```json
{
  "name": "onOfferClick",
  "payload": {}
}
```

Every `payload` includes `timestamp`, an ISO-8601 string.

### Events & Data

`onUpdate`: Emitted when the consumer submits a question in the flow. `updatePage` is the step slug from the question flow table above, so this is the event to use for funnel and drop-off reporting.

```json
{
  "name": "onUpdate",
  "payload": {
    "timestamp": "2026-04-07T00:00:00.000Z",
    "leadUuid": "00000000-0000-0000-0000-000000000000",
    "updatePage": "mortgage-info"
  }
}
```

`onOfferClick`: Emitted when the consumer clicks an offer call-to-action. `placement` distinguishes where the click happened: `offer-card` for the button on the offer card itself, and `more-info-modal` for the call-to-action inside the offer's More Info dialog.

```json
{
  "name": "onOfferClick",
  "payload": {
    "timestamp": "2026-04-07T00:00:00.000Z",
    "leadUuid": "00000000-0000-0000-0000-000000000000",
    "offerUuid": "1f5bf62b-9e0f-40ef-91ef-84b5c01942ac",
    "offerSearchUuid": "ab12cd34-ef56-7890-ab12-cd34ef567890",
    "placement": "offer-card"
  }
}
```

`onBrandLoaded`: Emitted when the embedded app has resolved your brand styling. If you use Engine's `<moneylion-mortgage>` component, you can ignore this event - the component applies the styling for you. It is relevant only if you host the iFrame directly.

`onOpenModal`: Emitted when the consumer opens an offer's More Info dialog, carrying the content to display. As with `onBrandLoaded`, Engine's component renders this dialog for you; the event matters only for a direct iFrame integration.

{% hint style="info" %}
Two events are SDK-only and are **not** emitted by the Engine web embed:

* `onBack`: emitted by the SDK header back button
* `onExit`: emitted by the SDK header exit button

Mortgage also does not emit `onRateTableRender`, `onNavigate`, `onCreate`, `onSubmit`, `onErrorPageView`, or `onErrorPageRetry`. If you have integrated another Engine embed, do not assume those events are available here - use `onUpdate` for flow progress and `onOfferClick` for conversion.
{% endhint %}

## Embed Best Practices & Troubleshooting

{% hint style="success" %}

#### Best practices

1. Use the snippet Engine gives you. Don't hardcode channel, zone, or component paths yourself.
2. Keep `async` on the script tag. This prevents the embed script from blocking the rest of your page.
3. Give the embed a real container. Set a width on the parent. Set a `min-height` when possible. This gives the iFrame room to render and avoids large layout shifts.
4. Allow Engine in your CSP. Your Content Security Policy must allow the Engine script in `script-src` and `https://www.moneylion.com` (or your Engine environment host) in `frame-src`.
5. Follow this page's tags guidance. Attributes differ by product. Use this page's sample, or your Engine-provided snippet, rather than copying syntax from another embed.
   {% endhint %}

{% hint style="warning" %}

#### Troubleshooting

The component doesn't show

1. Check your install mode. Custom element: confirm the `moneylion-mortgage` element from your snippet is on the page. Auto-mount: confirm `data-embed-type="auto-mount"` is on the script tag and the script is inside `<body>`.
2. Open the browser console. Check for script load failures or CSP blocks.

The page feels slow

1. Confirm the `async` attribute is on the script tag.
2. Avoid nesting the embed in a hidden container, such as `display: none`, at first load. This can delay useful height and layout work.

Events aren't firing

1. Confirm you listen for `message` events. Check for `{ name, payload }` objects. See the tracking section on this page for the events Mortgage actually emits.
2. In production, filter by Engine's origin. This ignores unrelated `postMessage` traffic from other page scripts.
   {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://even-financial.gitbook.io/developer-center/marketplace-integrations/web-embeds/mortgage-marketplace.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.