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