How to use TurnKey Lender Public API

How to get an API key 

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. 

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 enable this functionality.

Welcome page

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

Once a customer submits selecting loan term, these data should be saved in some way because these data points are needed on the next step to create a loan application.  On TurnKey Lender Front-Office, for example, the next Create an account page opens and all specified parameters are sent in the URL.  

Create an account page

Once a customer submits their login (email format is mandatory) and password, the following methods are used:

  • POST ​/Customer​/Register
    A new customer is registered in the system. tkLender_UserAuthToken is generated for their personal account. This token is required for all the endpoints used later on. 
    A new account is created 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 that you add a captcha to your web page(s) that create new user accounts and loans.

Application form

To save the provided customer's details, the following method can 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.  
    Feel free to find 'Customer details' object description for pure TurnKey Lender BOX editions  here: API. Customer Details structures.

    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'.  By doing this,  the customer's account status 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.
    Feel free to find 'Application form' specifications for pure TurnKey Lender BOX editions  here - Customer Details specifications

To add a document to the customer's details, the following steps need to be done:

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

  • In the PUT /Customer​/Details body, the 'Docs' (array) section is in the Customer Details object.  
    To add a new document to the customer's profile, it is necessary to only send the DocumentId of this file.  

  • GET /Customer​/Details
    This method returns all the info from the customer's authorized profile.
    For every linked document, an additional parameter, ID, is returned. This identifier defines the link between a document and the customer's profile. 
    It is required to send both Id and DocumentId with every following PUT /Customer​/Details request:

To unlink the document from the customer's profile, it is enough not to send the corresponding  'Id' and 'DocumentId' in the PUT /Customer​/Details request.

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 iframe for the integrated bank verification provider.

  • POST /PaymentOptions/BankVerification/SaveData
    Save all data received from 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 can provide a new password.  After that, this method is used to change the password in the system. 

Customer's Dashboard

Personal details

To show and manage customer's details, two methods can be used:

  • GET /Customer​/Details

  • POST /Customer​/Details

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

  • POST /Files/Upload

  • GET ​/Files​/GetInfo​/{documentId}

  • GET ​/Files​/Download

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 Archive, can be retrieved with the following 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}

  • GET /PaymentOptions/RepaymentAmounts/{loanId}

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