Guides
API Keys

Embedded Refinance

Before starting

This guide will assume you've already created and authenticated a user. If you haven't done that then please first read our User Connect guide.

Overview

Spinwheel allows you to offer your users refinance or origination in three different categories: Student Loan, Personal Loan, and Auto Loan. Using Spinwheel’s Refinance APIs and Drop-in Modules helps your users get pre-qualified for a loan. We then display offers in an optimized way to let the users know which offer is best for them, based on their goals.

To minimize friction, Spinwheel prefills data within the module based on information gathered from other integrations, such as Identity Connect.

Refinance Process

There are three primary steps to the refinance flow when using Spinwheel. Those steps are as follows:

  1. Create an application: /v1/financings/applications
  2. Submit the application: /v1/financings/apply
  3. Retrieve application offers: /v1/financings/results

🚧

Getting offers

It is important to note that retrieving application offers is an asynchronous process. It takes time for the loan servicer to return results to us so you may have to poll the /results endpoint until the application status changes to "COMPLETED" at which point your results should be available.

Results Statuses

When requesting results there are a number of statuses that you can expect. Please refer to the table below to understand what is meant by each status.

StatusExplanation
PENDINGThe application is processing on Spinwheel's servers. This status is very short-lived and is only expected for a second or two at most.
PROCESSINGThe application has been sent off to loan servicers and is awaiting results. When you see this status the expectation is that you will continue polling the results endpoint as the offers are not ready.
NO_RESULTSThe servicer was unable to provide results for the user. This typically occurs because the user did not match the criteria set out by the servicer, for example, their credit score was too low.
ERRORThere was an error processing the application. This may have been on Spinwheel's servers or with one of our servicers. If you see this repeatedly please reach out to us so we can investigate further.
COMPLETEDWe have successfully retrieved results from the requested servicer(s). You can expect to find offers under the results key.

📘

Prequalification

Spinwheel has built in pre-qualifications into our criteria, before passing the applications back to the servicers. As an example, if a student loan refinance requires a minimum credit score of 650, Spinwheel will not pre-qualify this user, and submit their information to the refinance servicer.

Reapplying

Once users submit the pre-qualifying form, Spinwheel saves the application information, so users can easily re-submit if their offers have expired, or if they would like to see if they now qualify.

If using the DIMs, the user can re-apply an existing application
If using the APIs, you can clone an existing application for a user and resubmit the new application

Helpful Tips and Best Practices

  • Presenting refinance to users should only be accessible if the user has a coordinating liability (ie. only suggest auto refinance if the user has an auto loan connected)
  • Partners should note prequalification criteria ahead of time, if they already have that data available from the user (ie. credit score, US citizen)

Useful Links

Required Fields by Liability Type

FieldStudent LoanAuto LoanPersonal Loan
type✅✅✅
loanAmount✅✅✅
loanPurpose✅
firstName✅✅✅
lastName✅✅✅
dateOfBirth✅✅✅
citizenshipStatus✅✅
ssn✅✅✅
email✅✅✅
addressLine1✅✅✅
city✅✅✅
state✅✅✅
zip✅✅✅
startDate✅✅✅
currentAddress✅✅✅
phoneNumber✅✅
schoolId✅
degree✅
startDate✅
endDate✅
annualIncome✅✅✅
isCurrent✅✅✅
type (employment)✅✅
employerName✅
position✅
value (assets)✅
monthlyExpense✅✅
type (expense)
VIN orlicensePlate✅
monthlyPayment✅
estimatedMileage✅
isNewVehicle✅

To learn more about our debt APIs and full product suite, visit spinwheel.io.

Updated 4 months ago