API Specifications

Post Request

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

Post Request Endpoints

Engine has two endpoints available to receive requests with user.

(Recommended) Asynchronous Flow

Endpoint: https://api.evenfinancial.com/leads/rateTables Partners building a Native API integration posting user information to this endpoint will need to make a separate request to retrieve offers. This is the more frequently utilized endpoint given the partner’s flexibility to retrieve offers from a separate endpoint.

Synchronous Flow

Endpoint: https://integrations.evenfinancial.com/blocking/leads/rateTables Partners building a Native API integration will receive offers back from Engine’s API after posting user information to this endpoint. Engine’s API will only respond when all financial institution responses have been resolved and as a result, the latency will be higher than the Asynchronous Flow endpoint.

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": "[email protected]",
    "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
  },
  "sessionInformation": {
    "ipAddress": "x.x.x.x"
  }
}

More information about key/value pair formatting and acceptable fields can be found in Engine by Moneylions API Reference (schemas).

productTypes array: "loan" and "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 info.

Response

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

Asynchronous & Synchronous Flow Responses

The method to retrieve offers from Engine by MoneyLion's API and response latency differ depending on which Post Request Endpoint was utilized.

Asynchronous Flow

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.

In the Asynchronous Flow, 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 – Link

• Poll the endpoint once every second up to 15 seconds or until “pendingResponses” is empty

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.

Synchronous Flow

Partners building a Native API integration will receive a response from Engine’s API with more latency than the Asynchronous flow, however the response will contain complete offer information.

Below is a mock of the API response for the Synchronous flow endpoint. Note that “pendingResponses” is empty as Engine has already received offers back for the user from all Financial Services partners.

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": []
}

specialOffersreturned in rate tables that also contain loanOffersare 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.