How to create your own Front-Office

TurnKey Lender offers the full stack of API methods which can be used by clients to create their own Front-Offices. This can be a website or a mobile application where your borrowers register, apply for loans, track their loan application statuses, sign contracts, pay with a single click, and more.

Let's go through the TurnKey Lender's Front-Office and clarify which API endpoints need to be used to build this functionality.

API key & Permissions

To send an API request to TurnKey Lender, an API key is required. You can generate as many keys as you need with different access permissions in your Back-Office. For details, read the article https://turnkey-lender.atlassian.net/wiki/spaces/TLKB/pages/1032651323

Open

Base URL

The full path to every API endpoint is created as follows: https://{site_domain_name}/PublicApi/{version}/{endpoint_path}.

To simplify reading this article, the base URL (https://{site_domain_name}/PublicApi/{version}) is omitted everywhere below. For example, the endpoint POST https://trial-us.turnkey-lender.com/PublicApi/v7-8/User/Login is called POST /User/Login.

User token

Once a customer creates their personal account or authorizes on the platform, their unique AuthToken  is generated. This token is required as tkLender_UserAuthToken almost for all endpoints below.  

Welcome page

Open

To create this web page, the following methods are used:

• GET /Customer/CreditProducts
  The info you get through this method lets you show the list of available credit products and bounds for the Loan amount and Term sliders. 

• GET /Customer/States
  If the 'States management' feature is enabled in the Back-Office, this method shows the list of states/provinces. 

  This feature applies to the United States edition and the Canada edition. 

• POST /Customer/Loans/Calculate
  Calculates the corresponding loan offer terms:  

• GET /Customer/PromoCode/Check
  If a customer provides a promo code, it should is checked and verified on the server side.

Once a customer submits selected loan terms, these data should be saved in some way while these data points are needed on the next step to create a loan application.  On TurnKey Lender Front-Office, for example, the next page (Create an account) opens, and all specified parameters are sent in the URL (for details, see https://turnkey-lender.atlassian.net/wiki/spaces/TLKB/pages/393380210).

Create an account page

Once a customer submits their login and password, the following methods are used:

• POST ​/Customer​/Register
  A new customer is registered in the system with the status 'Registration incomplete'.

• POST /Customer/Loans/Create
  A new loan is created for the authorized customer and the Public Loan ID is sent in response. A new loan is created with the 'Pre-Origination' status because Customer Details aren't filled out yet. Until they are, this loan is not visible on the Origination workplace of the Back-Office. 

We recommend you add a captcha to your web page(s) where customers create new accounts and loans.

Application form

To save the provided customer's details, the next method should be used:

• ​POST /Customer​/Details
  The list of the Application form fields depends on the project, that's why the Customer Details structure should be discussed with the TurnKey Lender development team.  

  It is possible to divide and send values in several batches, in case the Application form is split into multiple steps. 
  To avoid losing data, all previously sent data has to be resent with every new POST request. 

  To finalize filling in the Application Form, the parameter 'DetailsFilled' value should be set to 'true'. As a result, the status of the customer's account is changed to 'Active'.

  There is no validation of the customer's data on the server!
  The validation has to be implemented on the front end according to the application form specification.

If a customer wants to upload their Photo (as an avatar), the following methods should be used:

• POST ​/Files​/Upload
  This method uploads a new file to the TurnKey Lender server for the authorized customer. As a result, DocumentId is generated on the server and returned. 

• POST /Customer​/Details
  The received DocumentId should be sent as a value for the 'PhotoId’ parameter.

Personal & Loan Documents

To support Personal & Loan documents management, the following endpoints need to be done:

• GET /UserDocuments
  This endpoint is used to get all documents that are already linked to the customer’s profile or to one of their loan.
  This method is also useful to get the actual structure of document groups and their settings. Every group has its unique ‘Id’ that is required later to link any new file to the customer’s profile or loan with the endpoint PUT /UserDocuments.

• POST ​/Files​/Upload
  This method should be used every time when a new file needs to be uploaded to the database. As a result, ‘DocumentId’ is generated and returned. 

• PUT /UserDocuments
  This method is used to link a previously uploaded file to a customer’s profile or to a customer’s loan.

• GET /Files/GetInfo
  Using this method, it is possible to get all details of any previously uploaded file by its ‘DocumentId’.

• GET /Files/Download
  This method lets download any file to the customer’s device or create a preview.

• DELETE /UserDocuments
  To unlink a document from the customer's profile or loan, it is enough to apply the needed 'DocumentId' to this endpoint. The file is not erased from the database, so it is possible to use the same 'DocumentId' to link this file again to another document group or loan.

Verify bank account

This step is available if the 'Bank account verification' integration (Paid, Flinks, etc.) is enabled on the Back-Office and all credentials are correctly set there. 

At the same time, integration with the selected service should be implemented on the side of the custom Front-Office.

The diagram below shows how to use the API methods and this algorithm works for any built-in provider (see Integrations By Country):

• GET /PaymentOptions/BankVerification/Settings
  Get settings to open the iframe for the integrated bank verification provider.

• POST /PaymentOptions/BankVerification/SaveData
  Save all data received from the Bank verification service (iframe) in TurnKey Lender Database

• GET /PaymentOptions/BankVerification/IsDataProcessed
  Check if bank account verification is passed successfully and all data is received by TurnKey Lender.

Login page

Only one endpoint is needed to authorize a customer: 

• ​POST /User​/Login
  If a customer is authorized successfully, tkLender_UserAuthToken is generated for their personal account. This token is required for all further used endpoints.  

Restore password page

If a customer forgot their password, they have to provide their email  (the following method should be sent to the server): 

• POST ​/User​/RequestPasswordReset
  The required parameter 'confirmationUrl' should be linked to the 'Password change confirmation' page. 
  As a result, the password reset link is generated as 'confirmationUrl' in addition to the unique 'code' input parameter. This link is sent to the provided email in the 'Reset password' notification.  

• POST /User/ChangePassword
  Once the customer follows the link from the email, he is redirected to the 'Password change confirmation' page where a new password can be provided.  After that, this method is used to change the password in the system. 

Customer's Dashboard

Personal details

To display and manage customer details, two methods can be used:

• GET /Customer​/Details

• POST /Customer​/Details

The following endpoints are needed to manage customer's Personal documents:

• POST /Files/Upload

• GET ​/Files​/GetInfo​

• GET ​/Files​/Download

• GET /UserDocuments

• PUT /UserDocuments

• DELETE /UserDocuments

The authorized customer can change their password with the next method:

• POST ​/User​/ChangePassword

Bank Details

The following methods are designed for managing customer's payment options: 

• POST ​/PaymentOptions​/BankAccounts

• GET /PaymentOptions/BankAccounts

• POST /PaymentOptions/Cards

• GET /PaymentOptions/Cards

• PUT /PaymentOptions/Cards/{cardId}

• POST /PaymentOptions/SetDefaultMethod

• DELETE /PaymentOptions/DeleteMethod

Active loans 

The list of all customer's loans, which are not sent to the Archive, can be retrieved with the next method: 

• GET /Customer/Loans
  The received info is enough to display all general info about the loan, the actual loan schedule, the list of all repayment transactions, etc. 

Customers can pay directly from their dashboard if the following methods are used:

• POST ​/PaymentOptions​/SubmitRepayment​/{loanId}
  Submits repayment for a given loan. The funds will be automatically charged from the customer's card or bank account.

• GET /PaymentOptions/RepaymentAmounts/{loanId}
  Returns possible repayment amounts for a given loan

New loan

Creating a repeated loan (another loan taken out by the same customer) is much easier than creating the first one. Here are the required steps:

• GET /Customer/CreditProducts

• GET /Customer/States

• POST /Customer/Loans/Calculate

• GET /Customer/PromoCode/Check

• POST ​/Customer​/Loans​/Create