# Loans Marketplaces

This page covers prefilling Engine's lending marketplaces - Personal Loans, Student Loan Refinance (SLR), and Auto Loan Refinance (ALR) - using our Prefill API. 

It builds on the shared concepts in the Prefill API overview (how the flow works, token lifecycle, frontend options, best practices). Please start there if you haven't already!

## API Request

**Before you start:** you'll need a bearer token from your Engine team scoped to your Loans subaccount, and your lending experience configured and enabled by Engine.

### Authentication

Every request must be authenticated with the bearer token provided by your Engine team.

```
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

Your token is scoped to a specific subaccount **by product category** (Loans, Credit Cards, etc.). Use the token your Engine team directs you to use for each product — the markup you get back is determined by the marketplace tied to that token plus the `productTypes` you send.

### Request Body

Send a `POST` to the prefill endpoint with a JSON body. The body carries the consumer's data plus a `productTypes` array that tells Engine which experience to return.

{% hint style="warning" %}
`productTypes` is required. Without it, Engine can't determine which embed snippet and partner page URL to return, and the request will fail.
{% endhint %}

<table><thead><tr><th width="291.484375">Request Component</th><th>Value</th></tr></thead><tbody><tr><td>Endpoint</td><td><code>POST https://api.engine.tech/originator/prefills</code></td></tr><tr><td>Auth</td><td><code>Authorization: Bearer &#x3C;YOUR_ACCESS_TOKEN></code></td></tr><tr><td>Content Type</td><td><code>application/json</code></td></tr></tbody></table>

### Accepted Fields

{% hint style="info" %}
Group your data into the objects below. Send only what you have — **omitted fields are collected from the consumer in the Engine experience.**
{% endhint %}

All lending experiences use `productTypes:"loan"` and accept the same core fields:

<table><thead><tr><th width="206.0936279296875">Object</th><th width="220.4219970703125">Parameter</th><th>Notes</th></tr></thead><tbody><tr><td><code>personalInformation</code></td><td><code>productTypes</code></td><td><p><strong>Required array.</strong> </p><p></p><p><strong>Accepted Enums</strong>: <code>loan</code>, <code>credit_card</code>. Tells Engine which hosted experience (embed snippet + partner page URL) to return.</p></td></tr><tr><td><code>personalInformation</code></td><td><code>productSubType</code></td><td><p><strong>Optional:</strong> selects a specific lending experience when <code>productType</code> is <code>loan</code>. </p><p></p><p><strong>Accepted Enums:</strong> <code>auto_refinance</code>, <code>student_loan_refi</code>. </p></td></tr><tr><td><code>personalInformation</code></td><td><code>firstName</code></td><td>String</td></tr><tr><td><code>personalInformation</code></td><td><code>lastName</code></td><td>String</td></tr><tr><td><code>personalInformation</code></td><td><code>email</code></td><td>String</td></tr><tr><td><code>personalInformation</code></td><td><code>primaryPhone</code></td><td>String, 10-digit "0123456789"</td></tr><tr><td><code>personalInformation</code></td><td><code>address1</code></td><td>String</td></tr><tr><td><code>personalInformation</code></td><td><code>address2</code></td><td>Optional Address Field</td></tr><tr><td><code>personalInformation</code></td><td><code>city</code></td><td>String</td></tr><tr><td><code>personalInformation</code></td><td><code>state</code></td><td>String, standard two-letter code "NY"</td></tr><tr><td><code>personalInformation</code></td><td><code>zipcode</code></td><td>String</td></tr><tr><td><code>personalInformation</code></td><td><code>dateOfBirth</code></td><td>String, "YYYY-MM-DD"</td></tr><tr><td><code>personalInformation</code></td><td><code>ssn</code></td><td>String, "111-22-333"</td></tr><tr><td><code>loanInformation</code></td><td><code>purpose</code></td><td><a href="https://engine.tech/docs/api-reference/#tocS_LoanPurpose">Accepted Enums</a></td></tr><tr><td><code>loanInformation</code></td><td><code>loanAmount</code></td><td>Integer</td></tr><tr><td><code>mortgageInformation</code></td><td><code>propertyStatus</code></td><td><a href="https://engine.tech/docs/api-reference/#tocS_PropertyStatus">Accepted Enums</a></td></tr><tr><td><code>creditInformation</code></td><td><code>providedCreditRating</code></td><td><a href="https://engine.tech/docs/api-reference/#tocS_ProvidedCreditRating">Accepted Enums</a></td></tr><tr><td><code>financialInformation</code></td><td><code>employmentStatus</code></td><td><a href="https://engine.tech/docs/api-reference/#tocS_EmploymentStatus">Accepted Enums</a></td></tr><tr><td><code>financialInformation</code></td><td><code>employmentPayFrequency</code></td><td><a href="https://engine.tech/docs/api-reference/#tocS_EmploymentPayFrequency">Accepted Enums</a></td></tr><tr><td><code>financialInformation</code></td><td><code>annualIncome</code></td><td>Integer</td></tr></tbody></table>

#### Auto Loan Refinance

When Auto Loan Refinance is selected using `productSubType` , additional fields are accepted by the Prefill API:

| Object               | Field              | Notes   |
| -------------------- | ------------------ | ------- |
| `vehicleInformation` | `monthlyPayment`   | Integer |
| `vehicleInformation` | `estimatedMileage` | Integer |
| `vehicleInformation` | `vehicleUuid`      | String  |

#### Student Loan Refinance

When Student Loan Refinance is selected using `productSubType` , additional fields are accepted by the Prefill API:

| Object                 | Field                   | Notes                                                                            |
| ---------------------- | ----------------------- | -------------------------------------------------------------------------------- |
| `personalInformation`  | `citizenshipStatus`     | [Accepted Enums](https://engine.tech/docs/api-reference/#tocS_CitizenshipStatus) |
| `financialInformation` | `monthlyHousingPayment` | Integer                                                                          |
| `financialInformation` | `availableAssets`       | Integer                                                                          |
| `educationInformation` | `educationLevel`        | [Accepted Enums](https://engine.tech/docs/api-reference/#tocS_EducationLevel)    |
| `educationInformation` | `graduationDate`        | String, "YYYY-MM-DD"                                                             |
| `educationInformation` | `universityAttended`    | String                                                                           |
| `educationInformation` | `graduateDegreeType`    | [Accepted Enums](https://engine.tech/docs/api-reference/#tocS_IncentiveUnit)     |

### Sample Request Payloads

{% tabs %}
{% tab title="Personal Loan" %}

```json
{
  "productTypes": ["loan"],
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "city": "New York",
    "state": "NY",
    "primaryPhone": "2125556789",
    "address1": "45 West 21st Street",
    "address2": "5th Floor",
    "zipcode": "10010",
    "dateOfBirth": "1993-10-09",
    "ssn": "111-22-3333"
  },
  "loanInformation": {
    "purpose": "debt_consolidation",
    "loanAmount": 10000
  },
  "mortgageInformation": {
    "propertyStatus": "own_with_mortgage"
  },
  "creditInformation": {
    "providedCreditRating": "excellent"
  },
  "financialInformation": {
    "employmentStatus": "employed",
    "employmentPayFrequency": "weekly",
    "annualIncome": 120000
  },
  "educationInformation": {
    "educationLevel": "masters"
  }
}
```

{% endtab %}

{% tab title="Student Loan Refinance (SLR)" %}

```json
{
  "productTypes": ["loan"],
  "productSubType": "student_loan_refi",
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "city": "New York",
    "state": "NY",
    "primaryPhone": "2125556789",
    "address1": "45 West 21st Street",
    "address2": "5th Floor",
    "zipcode": "10010",
    "dateOfBirth": "1993-10-09",
    "ssn": "111-22-3333",
    "citizenshipStatus":"citizen"
  },
  "loanInformation": {
    "purpose": "debt_consolidation",
    "loanAmount": 10000
  },
  "mortgageInformation": {
    "propertyStatus": "own_with_mortgage"
  },
  "creditInformation": {
    "providedCreditRating": "excellent"
  },
  "financialInformation": {
    "employmentStatus": "employed",
    "employmentPayFrequency": "weekly",
    "annualIncome": 120000,
    "monthlyHousingPayment": 2500,
    "availableAssets": 50000
  },
  "educationInformation": {
    "educationLevel": "masters",
    "graduationDate":"2015-08-24",
    "universityAttended":"Johns Hopkins University",
    "graduateDegreeType":"master_of_science"
  }
}
```

{% endtab %}

{% tab title="Auto Loan Refinance (ALR)" %}

```json
{
  "productTypes": ["loan"],
  "productSubType": "auto_refinance",
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "city": "New York",
    "state": "NY",
    "primaryPhone": "2125556789",
    "address1": "45 West 21st Street",
    "address2": "5th Floor",
    "zipcode": "10010",
    "dateOfBirth": "1993-10-09",
    "ssn": "111-22-3333"
  },
  "loanInformation": {
    "purpose": "debt_consolidation",
    "loanAmount": 10000
  },
  "mortgageInformation": {
    "propertyStatus": "own_with_mortgage"
  },
  "creditInformation": {
    "providedCreditRating": "excellent"
  },
  "financialInformation": {
    "employmentStatus": "employed",
    "employmentPayFrequency": "weekly",
    "annualIncome": 120000
  },
  "educationInformation": {
    "educationLevel": "masters"
  },
  "vehicleInformation":{
  "monthlyPayment": 400,
  "estimatedMileage": 15020,
  "vehicleUuid": "e0993456-73e5-4005-99de-b40f8aacc8f0"
  }
}
```

{% endtab %}
{% endtabs %}

## API Response

A successful request returns `200 OK` with the token and the markup you need to render the experience.

| Field              | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `productTypes`     | Echoes the product types from your request.                                      |
| `prefillToken`     | The short-lived token that unlocks the prefilled data.                           |
| `expiresInSeconds` | Token time-to-live, in seconds (currently `180` seconds).                        |
| `maxUses`          | How many times the token can be redeemed (currently `3` uses before expiration). |
| `partnerPageUrl`   | Hosted Engine landing page, with the `prefillToken` already appended.            |
| `embedSnippet`     | HTML/JS markup to embed the experience on your own site.                         |

### Prefill Token Lifecycle

To keep consumer data secure, tokens have strict time and usage limits.

* **Time to live:** tokens are valid for `expiresInSeconds` (currently \~3 minutes / 180s). Generate the token immediately before the consumer interacts with the flow.
* **Usage:** tokens can be redeemed up to `maxUses` times (currently 3) to support retries. Do not cache or reuse a token across sessions.

{% hint style="info" %}
If the token's TTL or use limit is exceeded, the consumer simply isn't prefilled — they'll fill out the required fields themselves to complete the product search. Nothing breaks.
{% endhint %}

### Sample Response

The exact shape of `partnerPageUrl` and `embedSnippet` depends on the product marketplace.&#x20;

A successful Loans request returns the token plus the lending markup:

```json
{
  "productTypes": ["loan"],
  "prefillToken": "e9c6b1a2-4f8d-4d2c-b9e6-91f2a6d8b0a4",
  "expiresInSeconds": 180,
  "maxUses": 3,
  "partnerPageUrl": "https://www.moneylion.com/network/<your-marketplace>/loans/search/loan-purpose?prefillToken=e9c6b1a2-4f8d-4d2c-b9e6-91f2a6d8b0a4",
  "embedSnippet": "<script async src=\"https://www.moneylion.com/network/<your-marketplace>/loans/web-component/loans-search/index.js\" data-embed-type=\"auto-mount\" data-prefill-token=\"e9c6b1a2-4f8d-4d2c-b9e6-91f2a6d8b0a4\"></script>"
}
```

## Frontend Integration Options

Engine must configure and enable your experiences before they can render, regardless of which path you choose. The only dynamic value in the returned markup is the `prefillToken` — everything else is scoped to your marketplace and the `productTypes` you sent. You can extract and use any of:

* the full `partnerPageUrl`,
* the full `embedSnippet`, or
* just the `prefillToken` value (to drop into markup you already maintain)

### Partner Page (Linkout)

Best for partners who want to hand the consumer off to a hosted MoneyLion landing page, or who want a lighter-lift integration.

1. Extract `partnerPageUrl` from the response.
2. Redirect the consumer there with a standard HTTP 302 or a client-side location change.

### Embedded Experience

Best for partners who want to keep the consumer on their own property.

1. Extract `embedSnippet` from the response.
2. Unescape the snippet.
3. Inject the snippet into your page where the component should appear.
4. The script initializes automatically using the `prefillToken` to load the consumer's data.

{% hint style="warning" %}
The embed markup is **not** the same for every product — lending uses an auto-mounting script tag, while credit cards use a script plus a custom element. Use the snippet returned for your product, and see the product pages for the exact shape.
{% endhint %}

Lending uses a single **auto-mounting script tag**. The script reads `data-prefill-token` and mounts the experience automatically where you place it.

```html
<script
  async
  src="https://www.moneylion.com/network/<your-marketplace>/loans/web-component/loans-search/index.js"
  data-embed-type="auto-mount"
  data-prefill-token="e9c6b1a2-4f8d-4d2c-b9e6-91f2a6d8b0a4"
></script>
```

{% hint style="info" %}
This is different from the credit card embed, which uses a separate custom element. **Always** use the `embedSnippet` returned in your response.
{% endhint %}

## The Consumer Experience

{% hint style="info" %}
If you omit a field that shares a screen with others (e.g. part of an address), **consumers will be prompted for that whole screen rather than a single field.**
{% endhint %}

After the experience redeems the `prefillToken`, it patches the lead with the PII you sent and collects only what's missing:

* If everything is missing, the consumer fills out all required fields.
* If some data is missing, the consumer is prompted only for the missing required fields.
* If nothing is missing, the consumer skips straight to a review screen for consent.

### Review Screen

For compliance and security, the consumer is always shown a review screen before submission. It is fully editable, so they can correct anything that was prefilled.

* **Masking:** sensitive fields like SSN are masked (e.g. `***-**-6789`).
* **Confirmation:** the consumer must explicitly confirm the prefilled information.

### Fallback Behavior

If a token is invalid, expired, or fails to redeem, the consumer is **not** shown an error. The flow gracefully falls back to the standard manual application — they enter their information as if no prefill request had occurred.

## Reporting

{% hint style="warning" %}
**Please note:** actual `prefillToken` values are temporary and **cannot** be reported on. They are not stored permanently within Engine's platform.
{% endhint %}

You can include Client Tags exactly as you would for a standard embedded experience; see Engine's Client Tags & Reporting documentation:

* Partner Page Linkout: [Personal Loans Marketplace](/developer-center/embeddable-integrations/partner-pages/partner-pages.md#client-tags-and-prefilling-customer-data)
* Embedded Marketplace: [Personal Loans Marketplace](/developer-center/embeddable-integrations/widgets-and-embeds/embeds.md#client-tags-and-prefilling-customer-data)

## Best Practices

These practices keep consumer PII secure and prevent the most common integration mistakes. They apply to every Prefill API call, regardless of product.

### Request Timing

Generate the token immediately before the consumer enters the flow — it's valid for \~3 minutes and up to 3 uses.

### Never Place PII in the Browser

You must never pass PII in query parameters or embed codes on the client side.

* Don't append query-string parameters such as `&firstName=Jane` to URLs.
* Don't print user data into the HTML source.
* Always use the server-side API to exchange data for a `prefillToken`.

### Omit Missing Data from Requests

Any field you omit won't be prefilled. If you omit a field that shares a screen with other fields, none of the fields on that screen are prefilled — they're all collected from the consumer instead.

For example, if you omit `zipcode`, the consumer is prompted for the full address in-flow, rather than being asked only for a ZIP code. This is a deliberate product decision to avoid confusing, partially-filled screens.

## FAQ & Troubleshooting

<details>

<summary>What happens if the token expires before the consumer loads the page?</summary>

The consumer lands on the standard application and enters their information manually. The experience doesn't break — it reverts to a non-prefilled state.

</details>

<details>

<summary>Can I update the data after generating a token?</summary>

No. If the consumer's data changes, call the endpoint again to generate a new token.

</details>

<details>

<summary>Why did I get a <code>400 Bad Request</code>?</summary>

Make sure your JSON payload is well-formed and that `productTypes` is present and set to a valid value (`loan` or `credit_card`). If it still fails, confirm with your Engine team that you're using the correct bearer token for the product.

</details>

## Getting Help

For credentials, enabling experiences, or integration support, contact your Engine account team.


---

# 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:

```
GET https://even-financial.gitbook.io/developer-center/hybrid-api-integrations/second-party-prefill-api/loans-marketplaces.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.