Personal Loans

Flutter Personal Loans Mobile SDK Integration Guide

Overview

This documentation covers installation, required prerequisites, configuration properties currently surfaced (channel, zone), and a basic usage example.

Setup Instructions

You’ll need the correct channel and zone values for your integration. Ask your Partner Manager to provide these values for Flutter Personal Loans.

Step 1: Request an API Token

Before you can use the Engine SDK, you'll need to request an API token from your Partner Manager. This token is used to authenticate with the Engine API and provides access to different financial institutions. You may want to use multiple API tokens depending on how many entry points your app has into the SDK.

Step 2: Confirm Software Requirements

• Flutter 3.0.0 or higher

• Dart 3.10.7 or higher

Step 3: Install the SDK

Install the SDK via pub get:

flutter pub add engine_mobile_flutter_sdk

Note: This installs the latest compatible SDK version. For a specific version, pin it explicitly in pubspec.yaml.

Step 4: Initialize the SDK

In your app, initialize the SDK by adding the following imports to any Dart file where you want to use it. The second import exposes the prefill data models (imported with the engine prefix to avoid name collisions with Flutter):

import 'package:engine_mobile_flutter_sdk/engine_mobile_flutter_sdk.dart';
import 'package:engine_mobile_flutter_sdk/api_models.dart' as engine;

Basic Example

Place the EngineSDK widget anywhere in your widget tree to render the Personal Loan flow.

EngineSDK(
  channel: 'your-channel',
  zone: 'your-zone',
  productTypes: const [engine.ProductType.loan],
  onExit: (_) {
    debugPrint("Exit triggered from SDK");
    Navigator.pop(context);
  },
  // ...optional event handlers, please see Event Callbacks section below
)

Properties

Pass these properties to EngineSDK:

Prop	Type	Required	Description
channel	String	Yes	Identifies your integration in Engine. Provided by your Partner Manager (e.g. 'direct').
zone	String	Yes	Identifies the placement or distribution surface for the SDK. Provided by your Partner Manager (e.g. 'marketplace').
productTypes	List<ProductType>	Yes	Product flow(s) to render. Use [engine.ProductType.loan] for Personal Loans.
bearerToken	String	For prefill	API token from your Partner Manager. Required to use the Prefill API (the prefill props below). Without it, the standard non-prefilled flow renders.
personalInformation	LeadPersonalInformation	No	Prefill data (see Prefilling Lead Data below).
loanInformation	LeadLoanInformationJson	No	Prefill data (see Prefilling Lead Data below).
mortgageInformation	LeadMortgageInformationJson	No	Prefill data (see Prefilling Lead Data below).
creditInformation	LeadCreditInformationJson	No	Prefill data (see Prefilling Lead Data below).
financialInformation	LeadFinancialInformation	No	Prefill data (see Prefilling Lead Data below).
employmentInformation	LeadEmploymentInformationJson	No	Prefill data (see Prefilling Lead Data below).
legalInformation	LeadLegalInformationJson	No	Prefill data (see Prefilling Lead Data below).
educationInformation	LeadEducationInformationJson	No	Prefill data (see Prefilling Lead Data below).
clientTags	Map<String, List<String>>	No	Arbitrary key/value tags for reporting and attribution.
onExit	OnExitCallback	Yes	Fired when the user exits the flow.
onInitialize, onCreate, onUpdate, onNavigate, onSubmit, onRateTableRender, onOfferClick, onErrorPageView, onErrorPageRetry, onEmbedError, onEmbedErrorRetry	Callbacks	No	Optional tracking hooks. See the Event Handlers page.

User Experience Demo

The SDK renders a complete Personal Loans journey inside your app. It collects any missing user inputs, submits the lead, and then displays offers.

Typical flow:

1. Landing screen

2. Loan and personal details form

3. Review / confirm details

4. Offer results

Landing Screen

Loan Details

Personal Details

Personal Details

Personal Details

Personal Details

Client Tags for Reporting

The Engine Flutter SDK supports adding your unique Client Tags to track performance of specific campaigns or users. All Client Tag data is attributed to the lead level.

Client Tags can be added by including a clientTags attribute at the top level of the EngineSDK widget, where the value is a Map<String, List<String>>.

We strongly recommend including only one element per list for ease of reporting and attribution—if you want two separate tags, include the second tag under a different key. There is no limit to the number of keys in the clientTags map

Example

EngineSDK( 
bearerToken: '{your_token}', 
channel: '{your_channel}', 
zone: '{your_zone}', 
productTypes: const [engine.ProductType.loan], 
personalInformation: engine.LeadPersonalInformation(/* ...any data you don't want to ask for again */), 
clientTags: const { 
'clientId': ['client1'], 
'trafficsource': ['email'], 
'campaignId': ['campaign1'], 
}, 
// ...optional Event Handlers, please see Event Handler section 
)

Note: Client Tags are only sent as part of a prefill request. You must provide both a bearerToken and prefill data (via the information-class props such as personalInformation). If no prefill data is supplied, the SDK makes no prefill call and any clientTags you pass are ignored.

Supported Client Tag Keys for Reporting

If you plan for the Engine team to set up reporting (i.e., you do not plan to hit the Analytics API), these are the only keys that are currently fully supported. 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.

• agentId

• campaignId

• clientId

• deviceid

• medium

• sourceId

• subid

• subid1

• subid2

• subid3

• target

• trafficsource

• userid

See the GET Lead Client Tags endpoint for information on attributing lead analytics to your own client tags, if you decide to hit the Analytics API for reporting.

Prefilling Lead Data

This section describes how to prefill any user data you already have into your Flutter SDK implementation. Prefilled data is grouped into typed information classes and passed directly as props on EngineSDK. These models come from the api_models.dart import (aliased as engine).

Prefilling requires a bearerToken. Pass only the fields you have — omitted fields are collected from the user in-flow.

Example

EngineSDK(
  channel: 'your-channel',
  zone: 'your-zone',
  bearerToken: '{your_token}',
  productTypes: const [engine.ProductType.loan],
  personalInformation: engine.LeadPersonalInformation(
    firstName: 'Bob',
    lastName: 'Dylan',
    email: '[email protected]',
    dateOfBirth: DateTime(1990, 1, 1),
    primaryPhone: '2325624852',
    address1: '1600 Pennsylvania Avenue',
    address2: 'Apt 2',
    city: 'Washington',
    state: engine.State.DC,
    zipcode: '20500',
    ssn: '512-54-7862',
  ),
  loanInformation: engine.LeadLoanInformationJson(
    purpose: engine.LoanPurpose.creditCardRefi,
    loanAmount: 7500,
  ),
  mortgageInformation: engine.LeadMortgageInformationJson(
    propertyStatus: engine.PropertyStatus.ownWithMortgage,
  ),
  creditInformation: engine.LeadCreditInformationJson(
    providedCreditRating: engine.ProvidedCreditRating.good,
  ),
  financialInformation: engine.LeadFinancialInformation(
    employmentStatus: engine.EmploymentStatus.employedFullTime,
    employmentPayFrequency: engine.EmploymentPayFrequency.biweekly,
    annualIncome: 20000,
    bankRoutingNumber: '123456789',
    bankAccountNumber: '55555555555',
  ),
  employmentInformation: engine.LeadEmploymentInformationJson(
    directDeposit: false,
  ),
  legalInformation: engine.LeadLegalInformationJson(
    consentsToSms: true,
  ),
  educationInformation: engine.LeadEducationInformationJson(
    educationLevel: engine.EducationLevel.associate,
  ),
  onExit: (_) {},
)

Type Definitions

The information classes accept the following fields for Personal Loans (all fields optional):

class LeadPersonalInformation {
  final String? firstName;
  final String? lastName;
  final String? email;
  final DateTime? dateOfBirth;
  final String? primaryPhone; // 10 digits, no "+" or "-" chars
  final String? address1;
  final String? address2; // optional apartment / suite
  final String? city;
  final State? state; // enum, 2-letter (e.g. State.DC)
  final String? zipcode;
  final String? ssn; // 9 digits with or without hyphens
}

class LeadLoanInformationJson {
  final LoanPurpose? purpose; // enum below
  final int? loanAmount; // whole numbers only
}

class LeadMortgageInformationJson {
  final PropertyStatus? propertyStatus; // enum below
}

class LeadCreditInformationJson {
  final ProvidedCreditRating? providedCreditRating; // enum below
}

class LeadFinancialInformation {
  final EmploymentStatus? employmentStatus; // enum below
  final EmploymentPayFrequency? employmentPayFrequency; // enum below
  final int? annualIncome; // raw integer value (e.g. 20000)
  final String? bankRoutingNumber; // must be exactly 9 digits
  final String? bankAccountNumber;
}

class LeadEmploymentInformationJson {
  final bool? directDeposit;
}

class LeadLegalInformationJson {
  final bool? consentsToSms; // lead agrees to receive SMS
}

class LeadEducationInformationJson {
  final EducationLevel? educationLevel; // enum below
}

Enums / Accepted Values

Fields backed by an enum must use one of the predefined values:

enum LoanPurpose {
  auto,
  autoPurchase,
  autoRefinance,
  baby,
  boat,
  business,
  carRepair,
  cosmetic,
  creditCardRefi,
  debtConsolidation,
  emergency,
  engagement,
  green,
  homeImprovement,
  homePurchase,
  homeRefi,
  householdExpenses,
  largePurchases,
  lifeEvent,
  medicalDental,
  motorcycle,
  movingRelocation,
  other,
  rv,
  specialOccasion,
  studentLoan,
  studentLoanRefi,
  taxes,
  vacation,
  wedding,
}

enum ProvidedCreditRating {
  excellent,
  good,
  fair,
  poor,
  limited,
}

enum PropertyStatus {
  ownOutright,
  ownWithMortgage,
  rent,
}

enum EducationLevel {
  highSchool,
  associate,
  bachelors,
  masters,
  doctorate,
  stillEnrolled,
}

enum EmploymentStatus {
  employedFullTime,
  employedPartTime,
  selfEmployed,
  military,
  notEmployed,
  other,
}

enum EmploymentPayFrequency {
  biweekly,
  monthly,
  twiceMonthly,
  weekly,
}


// State is a 2-letter US state enum, e.g. State.CA, State.DC, State.NY

Do not prefill any fields that are empty or unavailable — omit them so the user is prompted in-flow. Prefilled data must match the type definitions above, and any field backed by an enum must use a valid value. If a value is invalid, that attribute is stripped and the user will have to enter it again manually.

Event Handlers Implementation

Event Handlers