API Specifications

Post Request

Engine by MoneyLion has two endpoints available to receive requests with user information:

(Recommended) Asynchronous Flow

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

Partners building a Native API integration will receive offers back from Engine by MoneyLion’s API after posting user information to this endpoint. Engine by MoneyLion’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 by MoneyLion’s will provide testing and production API access tokens. All requests to the Engine by MoneyLion’s 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-0b68f163f439

Post Request Body

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

{
  "productTypes": [
    "loans"
  ],
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "city": "New York",
    "state": "NY",
    "primaryPhone": "2125556789",
    "address1": "175 5th Ave",
    "address2": "",
    "zipcode": "10010",
    "dateOfBirth": "1992-10-04",
    "citizenshipStatus": "citizen",
    "ssn": "111-22-3333"
  },
  "loanInformation": {
    "purpose": "auto_refinance",
    "amount": 20000
  },
  "financialInformation": {
    "employmentStatus": "employed",
    "annualIncome": 200000,
    "monthlyHousingPayment": 1200
  },
  "mortgageInformation": {
    "propertyStatus": "own_outright"
  },
  "vehicleInformation": {
    "monthlyPayment": 510,
    "estimatedMileage": 2700,
    "vehicleUuid": "f4af8d7a-712b-401f-a4a0-0d5edde5970a"
  },
  "legalInformation": {
    "consentsToFcra": true,
    "consentsToTcpa": true,
    "fcraLanguage": "I am providing written consent under the Fair Credit Reporting Act (FCRA) for {Insert Company Name}, and its partners and financial institutions to obtain consumer report information from my credit profile.",
    "tcpaLanguage": "I agree to be contacted by Engine by MoneyLion and its partners at the telephone number(s) I have provided above to explore personal loan offers, including contact through automatic dialing systems, artificial or pre-recorded voice messaging, or text message. I understand my consent is not required as a condition to purchasing any goods or services from anyone."
  }
}

More information about key/value pair formatting and acceptable fields can be found here.

Querying the Vehicles Endpoint & Creating Dropdown Menus

It is recommended to pre-populate dropdown menus for 4 different vehicle fields: Year, Make, Model, and Trim. After collecting these values you will be able to capture the vehicle UUID to pass into the submit lead endpoint. Here is how we display it in our own experience:

Below are the steps to get a vehicle UUID:

• First, call GET /leads/vehicles/years to get the set of available vehicle years. Allow the consumer to select a year in the first dropdown menu.

  • The earliest year available will be 2002.

• Second, call GET /leads/vehicles/makes with the year parameter (captured previously) set to the value the consumer selected. Populate your make dropdown menu with the set of available makes for the selected year.

• Third, call GET /leads/vehicles/models with year and make parameters set to the values the consumer selected. Populate your model dropdown menu with the set of available models for the selected year and make.

• Finally, call GET /leads/vehicles/trims with year, make, and model parameters set to the values the consumer selected. This array will contain an array of objects with UUID and trim properties. Populate your trim dropdown menu using the trim property of the objects returned. Use the UUID field in the Rate Tables POST as vehicleInformation.vehicleUuid.

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 by MoneyLion’s API almost instantaneously. This response does not contain complete offer information and contains two key fields to retrieve offer information:

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

• “leadUuid” — Engine by MoneyLion’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 by MoneyLion is sending user information.

{
  "uuid": "83fc0258-59ef-488a-b2b8-9203e70f7dc2",
  "leadUuid": "501e8f55-8f4c-462e-91bb-f6114d1a620c",
  "loanAmount": 10000,
  "creditCardOffers": [],
  "lifeInsuranceOffers": [],
  "lineOfCreditOffers": [],
  "loanOffers": [],
  "mortgageOffers": [],
  "savingsOffers": [],
  "specialOffers": [],
  "pendingOriginators": [],
  "pendingResponses": [
    {
      "partner": {
        "uuid": "13beda09-8300-46c6-8dd6-87b87c4a93a3",
        "name": "Financial Service Partner Name",
        "description": "Description",
        "disclaimer": "Disclaimer",
        "imageUrl": "Image URL"
      },
      "productTypes": ["loan"]
    }
  ]
}

n the Asynchronous Flow, partners building a Native API integration must make a secondary request to Engine by MoneyLion’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 by MoneyLion’s Offers Endpoint

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

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

{
  "uuid": "83fc0258-59ef-488a-b2b8-9203e70f7dc2",
  "leadUuid": "501e8f55-8f4c-462e-91bb-f6114d1a620c",
  "loanAmount": 10000,
  "creditCardOffers": [],
  "lifeInsuranceOffers": [],
  "lineOfCreditOffers": [],
  "loanOffers": [
    ...
  ],
  "mortgageOffers": [],
  "savingsOffers": [],
  "specialOffers": [],
  "pendingOriginators": [],
  "pendingResponses": []
}

Synchronous Flow

Partners building a Native API integration will receive a response from Engine by MoneyLion’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 by MoneyLion has already received offers back for the user from all Financial Services partners.

{
  "uuid": "83fc0258-59ef-488a-b2b8-9203e70f7dc2",
  "leadUuid": "501e8f55-8f4c-462e-91bb-f6114d1a620c",
  "loanAmount": 10000,
  "creditCardOffers": [],
  "lifeInsuranceOffers": [],
  "lineOfCreditOffers": [],
  "loanOffers": [
    ...
  ],
  "mortgageOffers": [],
  "savingsOffers": [],
  "specialOffers": [],
  "pendingOriginators": [],
  "pendingResponses": []
}

Response Parsing

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

Errors

• 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.