Back to Engine.tech

API Specifications

Post Request

This section covers how user information is sent via requests to Engine by MoneyLion's API.

Post Request Endpoint

POST to https://api.engine.tech/leads/rateTables Partners building a Native API integration posting user information to this endpoint will need to make a separate request to retrieve offers.

Post Request Authorization

Engine will provide testing and production API access tokens. All requests to the Engine API must be authenticated using a bearer token specified in the Authorization header.

The header value is prefixed with the string “Bearer “, so a properly-authenticated request will look similar to the one here:

Authorization: Bearer 0a930e7f-4a96-4388-8c12-c901a161084e_409cc5f2-4008-11aa-84a4-0b68f163f437

Post Request Body - Object Structure

The required format of the body (JSON) in the request to Engine by MoneyLion's API is as follows:

{
  "productTypes": ["loan"],
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "city": "New York",
    "state": "NY",
    "primaryPhone": "2125556789",
    "address1": "175 5th Ave",
    "address2": "Apartment 5",
    "zipcode": "10010",
    "dateOfBirth": "1993-10-09",
    "ssn": "111-22-3333"
  },
  "loanInformation": {
    "purpose": "debt_consolidation",
    "loanAmount": 10000
  },
  "mortgageInformation": {
    "propertyStatus": "own_with_mortgage"
  },
  "creditInformation": {
    "providedCreditRating": "good"
  },
  "financialInformation": {
    "employmentStatus": "employed",
    "employmentPayFrequency": "biweekly",
    "annualIncome": 80000
  },
  "legalInformation": {
    "consentsToFcra": true,
    "consentsToTcpa": true,
    "fcraLanguage": "By checking this box/clicking 'agree' I hereby consent to the 'E-Sign Agreement', the 'Credit Authorization Agreement', the Terms of Service and Privacy Policy, and I am providing written consent under the Fair Credit Reporting Act (FCRA) for [Engine by MoneyLion and/or Insert Company Name], its partners and financial institutions to obtain consumer report information from my credit profile. I request that my information be provided to their partners, lenders, and financial services partners to provide me with financial recommendations, which may also include debt relief, credit repair, credit monitoring or other related services",
    "tcpaLanguage": "I agree to be contacted by [Engine by MoneyLion and/or Insert Company Name] its partners and their affiliated companies and financial institutions via email, postal mail service and/or at the telephone number(s) I have provided above to explore various financial products and services I inquired about, including contact through automatic dialing systems, artificial or pre-recorded voice messaging, or text message. Consent is not required as a condition to utilize the service, and you may choose to be contacted by an individual customer care representative(s) by calling XXXXX or emailing XXXX"
  },
  "sessionInformation": {
    "ipAddress": "x.x.x.x"
    "userAgent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36"
  }
}

Product Types

Field
Type
Required?
Sample Value
Enum/Comment

productTypes*

Array

Y

"loan", "other"

Enum:

  • "loan"

  • "loan", "other"

  • "other"

*In the productTypes array, you may pass ["loan"] (to receive First Look / Personal Loan offers only), ["other"] (to receive Second Look Marketplace offers only), or ["loan", "other"] if you want your leads to eligible for First Look offers when eligible, or else Second Look offers (if no First Look offers are received).

*See 2nd Look Marketplace (Channel Partners) for more information on how to directly access our 2nd Look Marketplace.

Personal Information

Field
Type
Required? (Yes/No/Conditional)
Sample Value
Enum/Comment

firstName

String

Y

John

First Name

lastName

String

Y

Doe

Last Name

email

String

Y

john@example.com

Email

city

String

Y

New York

City

state

String

Y

NY

State 50 U.S. states + DC (District of Columbia) + PR (Puerto Rico) + VI (U.S. Virgin Islands)

primaryPhone

String

Y

2125556789

See below Regex Validations for more information

address1

String

Y

45 West 21st Street

address2

String

N

5th Floor

Optional

zipcode

String

Y

10010

See below Regex Validations for more information

dateOfBirth

String

Y

1993-10-09

Date of Birth

ssn

String

Y

111-22-3333

Social Security Number. See below Regex Validations for more information

Loan Information

Field
Type
Required? (Yes/No)
Sample Value
Comment

purpose

String

Y

debt_consolidation

See enum at API reference - purpose

loanAmount

Integer

Y

1000

Unit in USD

Mortgage Information

Field
Type
Required? (Yes/No)
Sample Value
Comment

propertyStatus

String

Y

own_with_mortgage

See enum at API reference - propertyStatus

Credit Information

Field
Type
Required? (Yes/No/Conditional)
Sample Value
Comment

providedCreditRating

String

Conditional

good

See enum at API reference - providedCreditRating

providedNumericCreditScore

Int

Conditional

750

Either providedCreditRating or providedNumericCreditScore must be present

Financial Information

Field
Type
Required? (Yes/No/Conditional)
Sample Value
Enum/Comment

employmentStatus

String

Yes

employed

See enum at API reference - employmentStatus

employmentPayFrequency

String

Yes

weekly

See enum at API reference - employmentPayFrequency

annualIncome

Integer

Yes

100000

Unit in USD

Education Information

Field
Type
Required? (Yes/No/Conditional)
Sample Value
Enum/Comment

educationLevel

String

N

masters

See enum at API reference - educationLevel

Legal Information

Field
Type
Required? (Yes/No/Conditional)
Sample Value
Enum/Comment

consentsToFcra

Boolean

Yes

true

Required. Must be set to true.

fcraLanguage

String

Yes

"By checking this box/clicking 'agree' I hereby consent to ..."

Required. Must include the exact FCRA language shown to users.

consentstoTcpa

Boolean

No

true

Highly recommended*

tcpaLanguage

String

Conditional

"By checking this box/clicking 'agree' I hereby consent to ..."

Required only if consentsToTcpa is true. Must include the exact TCPA language shown to users.

*Although the FCC has postponed the effective date of the TCPA One-to-One Consent Rule—meaning the consentsToTcpa field is no longer strictly required (i.e. does not need to be true—Engine still strongly encourages our channel partners to obtain user consent to maintain the highest standards of compliance and performance.

Session Information

Field
Type
Required? (Yes/No)
Sample Value
Enum/Comment

ipAddress

String

Yes

8.8.8.8

Used for fraud detection by FI partners

userAgent

String

Yes

Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36

Used for fraud detection by FI partners

Regex Validations

The following fields have the regex checks and will return errors if your lead submission does not adhere to this logic:

personalInformation.primaryPhone

The primary must be a string of 10 digits, with or without a leading 1, and with or without special characters e.g. ()-.

The area code cannot be the same 3 digits repeated, e.g. 222or 333.

personalInformation.zipcode

The zipcode must be a string of either:

  1. 5 digits

  2. 5 digits, a hyphen -, and 4 more digits

personalInformation.ssn

  1. The SSN cannot have all digits in each group be identical (e.g., 111-11-1111 or 222-22-2222).

  2. The following specific SSNs are not allowed because they are commonly used in examples or considered invalid:

  • 123-45-6789

  • 219-09-9999

  • 078-05-1120

  1. The first group of three digits cannot be:

  • 666

  • 000

  • Any number starting with 9 (e.g., 900–999).

  1. The middle group of two digits cannot be:

  • 00

  1. The last group of four digits cannot be:

  • 0000

Response

This section covers how partners building a Native API integration retrieve offers from Engine by MoneyLion's API.

Partners building a Native API integration will receive a response from Engine’s API almost instantaneously. This response does not contain complete offer information and contains two key fields to retrieve offer information:

  • “uuid”: Engine’s Rate Table UUID which will be used to retrieve offer information

  • “leadUuid”: Engine’s Lead UUID which partners building a Native API integration should store for internal records

Here is an example of the API response for the Asynchronous flow endpoint. Note that pendingResponses contains information about the Financial Services partners to whom Engine is sending user information.

Partners building a Native API integration must make a secondary request to Even’s API to retrieve offer information. Below are instructions for this secondary request:

  • Capture the uuid returned in the initial API response

  • Execute a GET request to Engine’s Offers Endpoint:

    • GET https://api.engine.tech/originator/rateTables/:uuid

  • Poll the GET rateTables endpoint once every second until “pendingResponses” is empty (either up to 15s or 30s, depending on whether 2nd Look Marketplace offers are also enabled. (Please see Response Timing section below for more info.)

Below is a mock of the API response for Even’s Offers endpoint. Note that pendingResponses is empty as Even has already received offers back for the user from all Financial Services partners.

Response Timing

Below are p25, 50, 75, and 95 response times across our network of Financial Institution API Partners (current as of 2/28/25). You can use this to estimate the average time it will take for Engine's rate table response to fully resolve (i.e. no more pendingResponses) - please see notes below the table.

Response Times by Marketplace - Table

1st Look

Percentile
Response Time (seconds)

p25

1

p50

2

p75

4

p95

8

2nd Look Response Time

Percentile
Response Time (seconds)

p25

<1

p50

1

p75

4

p95

11

Engine will respond immediately (average response times are <1 second), but you will need to keep GETting the resulting rate table until the pendingResponses array is empty. The table above shows the time it will take until you no longer need to poll /rateTables/:uuid.

1st Look, 2nd Look, or 1st Look + 2nd Look Waterfall

If you are set up for only 1st Look or 2nd Look through your integration (i.e. if you are only including one value in the productTypes array, either ["loan"] or ["other"], you can use the times above as an indication of the time for a rate table to fully resolve.

If you are set up with the 1st Look / 2nd Look waterfall (i.e. productTypes = ["loan", "other"], where Engine waits for all 1st Look Partners to respond before submitting to 2nd Look partners, you should add the 1st Look response times to the 2nd Look response times to interpret the time it takes for the rate table to fully resolve with offers.

Caveat - Full API Gateway May Take Longer

This only displays the time it takes for Financial Institutions to respond to Engine's API requests. The full end-to-end experience may take longer than the times in the table above, considering the full flow of info from one end to the other:

  • What is typically negligible: the additional time from the time your request hits Engine before we initiate those requests, and the time for Engine to respond to you after our Financial Institution partners respond to us.

  • What may not be negligible: the additional time it takes for the user/client to make the request to the Engine API via your own API, and the additional time it takes for the user/client to process the response they receive by your API.

Response Parsing

loanOffers array

Offers will be returned in the loanOffersarray, and only that array should be used to display loan offers (aka 1st Look offers).

Rate tables with loanOffers present may also contain offers in the specialOffers array, for example:

{
    "uuid": "4e016504-f728-450c-9c3a-fd012057e3dc",
    "leadUuid": "09a589c8-b6be-427f-ab09-450408742dbb",
    "creditCardOffers": [],
    "lifeInsuranceOffers": [],
    "lineOfCreditOffers": [],
    "loanOffers": [
        {
            "uuid": "0c66af13-ddaf-4493-bacf-c6c9c0a5bbc9",
            "originator": {
                "key": "engine-demo-loans-demand-sub-account-1",
                "name": "Engine Demo Loans Demand Sub Account 1",
                "description": "Demo Sub Account 1 - Description: This is a description of the FI, usually marketing material. <b> This section may include html.</b>",
                "images": [
                    {
                        "sizeKey": "120x40",
                        "url": "https://s3.amazonaws.com/images.evenfinancial.com/logos/dev/engine_demo_loans_demand_sub_account_1-202-wqm88e4a.png"
                    }
                ],
                "disclaimer": "<p>Demo Sub Account 1 - Disclaimer: This is a disclaimer on the FI/offer, usually includes: \n<ul>\n<li>Legal Terms</li>\n<li>Stipulations</li>\n<li>Limitations</li>\n</ul>\n</p>\n<br/>\n<p>On occasion there may be a separate <a href=\"www.google.com\" target=\"_blank\">hyperlink to another site</a>, or <sup>1</sup>other tag types.</p>\n<br/>\n<sup>1</sup>These are common disclaimer conventions solved by the inclusion of basic HTML",
                "companyUuid": "d50195db-34f8-4dda-8702-e87165cce17d",
                "financialInstitutionUuid": "fa8ed168-9a3e-4612-aa2a-47781dede8f1"
            },
            "originatorId": null,
            "termLength": 36,
            "termUnit": "month",
            "maxAmount": 10000,
            "minAmount": 10000,
            "maxApr": 13.99,
            "minApr": 13.99,
            "meanApr": 13.99,
            "feeRate": null,
            "maxFeeRate": null,
            "minFeeRate": null,
            "feeFixed": null,
            "maxFeeFixed": null,
            "minFeeFixed": null,
            "allowPrepayment": true,
            "prepaymentFee": null,
            "monthlyPayment": 341.73,
            "maxMonthlyPayment": 341.73,
            "minMonthlyPayment": 341.73,
            "meanMonthlyPayment": 341.73,
            "maxTotalPayment": 12303,
            "minTotalPayment": 12303,
            "meanTotalPayment": 12303,
            "terms": null,
            "url": "https://offers.moneylion.com/ref/6a946016-702f-4e8c-8b3b-1d194d6743fb",
            "preQualified": true,
            "preApproved": false,
            "secured": false,
            "sponsored": false,
            "recommendationScore": null,
            "productType": "loan",
            "productSubType": "personal_loan",
            "payout": null,
            "aprType": "fixed",
            "coApplicant": false,
            "aprDescription": null,
            "displayTermUnit": null,
            "productSubTypeDisclaimer": null,
            "monthlyPaymentDescription": null,
            "termDescription": null,
            "amountPrefix": null
        },
        {...other loan offers}
    ],
    "mortgageOffers": [],
    "savingsOffers": [],
    "specialOffers": [
        {
            "uuid": "8ddc320c-2a52-4c87-ba35-bfce3a8a7b3a",
            "name": "Mock Credit Builder Offer",
            "desc": "Description of the credit builder offer",
            "url": "https://offers.moneylion.com/ref/37089591-5d47-4219-a532-a65f7bd8c535",
            "partnerName": "Engine Demo Loans Demand Sub Account 1",
            "partnerImageUrl": "https://s3.amazonaws.com/images.evenfinancial.com/logos/dev/engine_demo_loans_demand_sub_account_1-202-wqm88e4a.png",
            "productSubType": "credit_builder",
            "disclaimer": "test special offer disclaimer 1",
            "financialInstitutionUuid": "fa8ed168-9a3e-4612-aa2a-47781dede8f1"
        }
    ],
    "pendingOriginators": [],
    "pendingResponses": []
}

specialOffers returned in rate tables that also contain loanOffers are static 2nd Look (i.e. non-loan) offers that are unlikely to be a match for the applicant requesting a loan, and should be ignored.

You should write your display logic such that:

  • If loanOffers is present and non-empty, display all loan offers.

  • If loanOffers is empty, display specialOffers.

Leads posted with productTypes: ["loan", "other"] will always get either loanOffers or specialOffers in the resulting rate table.

Response field mapping

Below is the mapping of the required fields for the offer display page to the fields present in the “loanOffers” section of the API response:

Key

Value

Financial Services Partner Logo

originator.images.url

Offer Amount

maxAmount

Offer Term Length

termLength

Offer Term Unit

termUnit

Offer Term Description

termDescription

Offer APR Amount (%)

maxApr

Offer APR Description

aprDescription

Offer Monthly Payment Amount

maxMonthlyPayment

Offer Monthly Payment Description

monthlyPaymentDescription

• If “preApproved” is “true”

• If “preQualified” is “true”

• If both “preApproved” & “preQualified” are “true”

• Pre-Approved

• Pre-Qualified

• Pre-Approved

Offer Disclaimer

originator.disclaimer

For the additional fields required for Secured Loans or Line of Credit products:

Key

Value

Product Type Label

productSubType

Product Type Disclaimer

productSubTypeDisclaimer

Errors

Response types are mapped to HTTP status codes. In particular:

  • 200 OK: when data is successfully returned for a GET request

  • 201 Created: when new data is submitted to via a POST

  • 400 Bad Request: the submitted data is malformed

  • 401 Unauthorized: when the Authorization header is missing, if the value is invalid, or if the corresponding access token lacks the required scopes to complete the request

  • 404 Not Found: the URL is invalid, or the resource ID reference in the URL does not exist

  • 422 Unprocessable Entity: the submitted data is properly formatted, but invalid according to business logic (some legacy endpoints use 409 Conflict in this case)

  • 5xx: server error

Minor version changes to the API are guaranteed to be backwards compatible. Major version changes may break the API, but legacy versions are supported indefinitely.

PreviousDisplaying Personal Loan OffersNextFAQs

Last updated

Was this helpful?