🛠️Contributor API development guide
This guide provides the options and technical specifications for developing and securely consuming the specified REST API endpoint securely and effectively.
1.Contributor API endpoint
2.Data points set
Below is the set of data points that needs to be available as JSON trought the contributor`s API. A proposed JSON structure is shared in section Response of a borrower data request
RecordID
String
Y
123456789
Unique Identifier
kycSurname
String
Y
Doe
Borrower Surname
kycFirstName
String
Y
John
Borrower First name
kycMiddleName
String
N
Smith
Borrower Middle name
kycDateOfBirth
Date
Y
1990-01-01
Borrower Date of Birth
kycIdNumber
String
Y
ABC123456
Borrower ID number
kycIDType
Int
Y
1
0 - Other 1 - SSS 2 - TIN 3 - National Id 4 - Passport 5 - Driver's licence 6 - Philhealth 7 - Professional Regulation Commission 8 - Unified Multi-Purpose Id 9 - Voter's Id 10 - PhilSys 11 - Postal Id
kycMobilePhone
String
Y
63XXXXXXXXXX
Borrower Mobile number
kycAddress
String
N
123 Main St, Anytown, USA
Borrower Address
loanInfoLoanType
Int
Y
1
0 - Other 1 - PayDayLoan 2 - POS 3 - CashLoan 4 - CreditLine 5 - CreditCard 6 - AutoLoan 7 - MotorcycleLoan 8 - HomeLoan
loanInfoApplicationDate
Date
Y
2022-01-01
Loan Application date
loanInfoOpenDate
Date
Y
2022-01-01
Loan Open date
loanInfoLoanTerm
Int
Y
5
Count of months, loan term.
loanInfoOpenBalance
Float
Y
10000
Loan Open Balance
loanInfoOutstandingBalance
Float
Y
8000
The total amount the borrower still owes as of the time of enquiry, including principal, accrued interest, and applicable fees. Can be '0' if there isn't an outstanding balance
loanInfoNextDueDate
Date
Y
2024-05-01
Loan Next Due date
loanInfoStatusCode
String
Y
Active
Active, Delayed, Collection, Written off, Closed, Rejected, Incomplete, Not Disbursed
loanInfoInstallmentAmount
Float
Y
500
Loan installment amount
loanInfoRepaymentFrequency
Int
Y
1
0 - Other 1 - Monthly 2 - Biweekly 3 - SinglePayment
loanInfoRepaymentFullHistory
Array of Objects
Y
{ "dueDate": "15-03-2024", "paymentDate": "15-03-2024", "paymentAmount": 1300.00 }, {"dueDate": "15-04-2024", "paymentDate": "15-04-2024", "paymentAmount": 1250.50}, {"dueDate": "15-05-2024", "paymentDate": "15-05-2024","paymentAmount": 1275.75 }, { "dueDate": "15-06-2024", "paymentDate": "15-06-2024", "paymentAmount": 1320.25 }, {"dueDate": "15-07-2024","paymentDate": "15-07-2024","paymentAmount": 1295.00}
An array of objects detailing each payment made on the loan, including the due date, actual payment date, and payment amount. If a payment was not made, paymentDate is null.
loanInfoCloseDate
Date
Y
2024-05-25
Loan Close Date
Detailed descriptions for the variables can be found here https://docs.google.com/spreadsheets/d/1ChI0ldz1yBr1bRYjZ6PeuXNahE0kwWyN/edit?usp=drivesdk&ouid=102629089778994761174&rtpof=true&sd=true
3.Technical overview
This document explains how Contributors should return data when they get an API request from the LenderLink API. It covers the authentication methods and parameters needed to make the process easy and straightforward. This way, when a lender makes a request for a specific number to the LenderLink API, we will be able to obtain this information from the contributors.
API response layout
The structure of the Contributor Database table to be used as a layout for the API response.
The contributors should keep the data, which will be returned to LendeLink upon enquiry, up-to-date.
The response data should be generated in real-time or reflect data as of the most recent update (the same day or the day before).
Authentication Method
The API you are going to build must include some form of authentication. This could be either JWT (JSON Web Token) as a Bearer token, or a simple one-time generated token that you provide to LenderLink.
Additionally, IP whitelisting can be implemented, especially if using a one-time token.
Request for a Borrower Data
Contributors should build a REST API endpoint which accepts a request payload with the Query parameters below, and returns a detailed response containing KYC and loan information.
Example API Endpoint
GET API URL (Endpoint)
https://somedomain.com/api/v1/borrowerRequest Headers
Content-Type: application/jsonAuthorization: Token <token>
Multi Parameters Search Query :
A Multiple parameters search should be implemented. LenderLink will send API calls containing all the parameters below.
requestId
String
Unique identification code generated by the client
firstName
String
First Name
lastName
String
Last Name
dateOfBirth
Date
Date of Birth - YYYY-MM-DD
cellphoneNumber
String
Borrower's phone number, the format is 63XXXXXXXXXX.
String
Borrower's email address
idNumber
String
Borrower's ID document number. ID, Driver license, etc
Once the parameters have been accepted and the database search has begun, it is very important to ensure adequate results, the firstName, lastName and dateOfBirh parameters should be used as combination of the three. That means you should not use them individually or in a broad OR with everything else — doing so might return unrelated rows.
Example of proper usage:
SELECT *
FROM db_table
WHERE mobilePhone = '693XXXXXXXXX'
OR email = '[email protected]'
OR (firstName = 'John' AND lastName = 'Doe' AND dateOfBirth = '1987-03-24');Here is example of improper usage:
SELECT *
FROM db_table
WHERE mobilePhone = '693XXXXXXXXX'
OR email = '[email protected]'
OR firstName = 'John' ;Response of a borrower data request
The data should be split into 4 blocks (for each search criteria) depending on the search criteria with which the loan was found.
For example if the same loan was found by two different criteria this will result in the one response with two blocks that hold the exact same information but returned in the different search criteria blocks.
LenderLink will apply the appropriate match flags to the response and process it further. We are also going to apply deduplication on the data so you can skip that step at your side if you prefer.
Example response:
Success Response
{
"mobilePhone":[
{
"recordId": "X123-AB45",
"kycSurname": "Doe",
"kycFirstName": "John",
"kycMiddleName": "Smith",
"kycDateOfBirth": "1990-01-01",
"kycIdNumber": "ABC123456",
"kycIdType": 4,
"kycMobileNumber": "639170000001",
"kycEmailAddress": "[email protected]",
"kycAddress": "123 Main St, Anytown, USA",
"loanInfoLoanType": 1,
"loanInfoApplicationDate": "2024-01-01",
"loanInfoOpenDate": "2024-01-01",
"loanInfoLoanTerm": 5,
"loanInfoOpenBalance": 10000,
"loanInfoOutstandingBalance": 8000,
"loanInfoNextDueDate": "2024-06-01",
"loanInfoLastPaymentAmount": 200,
"loanInfoLastPaymentDate": "2024-07-01",
"loanInfoStatusCode": "Active",
"loanInfoInstallmentAmount": 500,
"loanInfoOverdueAmount": 100,
"loanInfoRepaymentFrequency": 1,
"loanInfoRepaymentHistory": "0000",
"loanInfoCloseDate": "2024-05-25",
"contributorId": "12d3ae45-678d-9ae1-2345-6e789e3xx000",
"loanInfoRepaymentFullHistory": [
{
"dueDate": "15-03-2024",
"paymentDate": "15-03-2024",
"paymentAmount": 1300.00
},
{
"dueDate": "15-04-2024",
"paymentDate": "15-04-2024",
"paymentAmount": 1250.50
},
{
"dueDate": "15-05-2024",
"paymentDate": "15-05-2024",
"paymentAmount": 1275.75
},
{
"dueDate": "15-06-2024",
"paymentDate": "15-06-2024",
"paymentAmount": 1320.25
},
{
"dueDate": "15-07-2024",
"paymentDate": "15-07-2024",
"paymentAmount": 1295.00
}
]
}
],
"firstName|lastName|dateOfBirth": [
{
"recordId": "X123-AB45",
"kycSurname": "Doe",
"kycFirstName": "John",
"kycMiddleName": "Smith",
"kycDateOfBirth": "1990-01-01",
"kycIdNumber": "ABC123456",
"kycIdType": 4,
"kycMobileNumber": "639170000001",
"kycEmailAddress": "[email protected]",
"kycAddress": "123 Main St, Anytown, USA",
"loanInfoLoanType": 1,
"loanInfoApplicationDate": "2024-01-01",
"loanInfoOpenDate": "2024-01-01",
"loanInfoLoanTerm": 5,
"loanInfoOpenBalance": 10000,
"loanInfoOutstandingBalance": 8000,
"loanInfoNextDueDate": "2024-06-01",
"loanInfoLastPaymentAmount": 200,
"loanInfoLastPaymentDate": "2024-07-01",
"loanInfoStatusCode": "Active",
"loanInfoInstallmentAmount": 500,
"loanInfoOverdueAmount": 100,
"loanInfoRepaymentFrequency": 1,
"loanInfoCloseDate": "2024-05-25",
"contributorId": "12d3ae45-678d-9ae1-2345-6e789e3xx000",
"loanInfoRepaymentFullHistory": [
{
"dueDate": "15-03-2024",
"paymentDate": "15-03-2024",
"paymentAmount": 1300.00
},
{
"dueDate": "15-04-2024",
"paymentDate": "15-04-2024",
"paymentAmount": 1250.50
},
{
"dueDate": "15-05-2024",
"paymentDate": "15-05-2024",
"paymentAmount": 1275.75
},
{
"dueDate": "15-06-2024",
"paymentDate": "15-06-2024",
"paymentAmount": 1320.25
},
{
"dueDate": "15-07-2024",
"paymentDate": "15-07-2024",
"paymentAmount": 1295.00
}
]
}
]
}
NB! In case there is information for more than one loan in the current response, the information is returned as each loan follows the structure described in the table, collected in an array (array of JSON object, each one following the example above).
For loanInfoStatusCode: "Rejected" , when you encounter a rejected borrower, you should return an object similar to the one below. But in the structure above.
{
"recordId": "123456789",
"kycSurname": "Doe",
"kycFirstName": "John",
"kycMiddleName": "Smith",
"kycDateOfBirth": "1990-01-01",
"kycIdNumber": "ABC123456",
"kycIdType": 4,
"kycMobileNumber": "639123456789",
"kycEmailAddress": "[email protected]",
"kycAddress": "123 Main St, Anytown, USA",
"loanInfoLoanType": null,
"loanInfoApplicationDate": "2022-01-01",
"loanInfoOpenDate": null,
"loanInfoLoanTerm": null,
"loanInfoOpenBalance": null,
"loanInfoOutstandingBalance": null,
"loanInfoNextDueDate": null,
"loanInfoLastPaymentAmount": null,
"loanInfoLastPaymentDate": null,
"loanInfoStatusCode": "Rejected",
"loanInfoInstallmentAmount": null,
"loanInfoOverdueAmount": null,
"loanInfoRepaymentFrequency": null,
"loanInfoCloseDate": null,
"loanInfoRepaymentFullHistory": null
}4.Backup option
If the contributor is not API ready yet as a backup option we can use a SFTP integration as described below.
Last updated