# Contributor API development guide

### 1.Contributor API endpoint

<figure><img src="https://2535431771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA6bXF0ByrsIRc0FWtxRe%2Fuploads%2FNQNyIYLIDMwYO2pmChJJ%2FSlide2.jpg?alt=media&#x26;token=114ef91b-62c8-4b00-96fa-2369f397c937" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2535431771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA6bXF0ByrsIRc0FWtxRe%2Fuploads%2FDG3A4InT7EoVwwIrYgz6%2FSlide3.jpg?alt=media&#x26;token=3e3512b5-1d21-4cba-92ba-9e0dc8f04b04" alt=""><figcaption></figcaption></figure>

### 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](#response-of-a-borrower-data-request "mention")

<table data-full-width="true"><thead><tr><th width="252.68359375">Variable Name</th><th width="115.03515625">Type</th><th width="105.32421875">Required</th><th width="388">Example Value</th><th width="283">Comments</th></tr></thead><tbody><tr><td>RecordID</td><td>String</td><td>Y</td><td>123456789</td><td>Unique Identifier</td></tr><tr><td>kycSurname</td><td>String</td><td>Y</td><td>Doe</td><td>Borrower Surname</td></tr><tr><td>kycFirstName</td><td>String</td><td>Y</td><td>John</td><td>Borrower First name</td></tr><tr><td>kycMiddleName</td><td>String</td><td>N</td><td>Smith</td><td>Borrower Middle name</td></tr><tr><td>kycDateOfBirth</td><td>Date</td><td>Y</td><td>1990-01-01</td><td>Borrower Date of Birth</td></tr><tr><td>kycIdNumber</td><td>String</td><td>Y</td><td>ABC123456</td><td>Borrower ID number</td></tr><tr><td>kycIDType</td><td>Int</td><td>Y</td><td>1</td><td>0 - Other<br>1 - SSS<br>2 - TIN<br>3 - National Id<br>4 - Passport<br>5 - Driver's licence<br>6 - Philhealth<br>7 - Professional Regulation Commission<br>8 - Unified Multi-Purpose Id<br>9 - Voter's Id<br>10 - PhilSys<br>11 - Postal Id</td></tr><tr><td>kycMobilePhone</td><td>String</td><td>Y</td><td>63XXXXXXXXXX</td><td>Borrower Mobile number</td></tr><tr><td>kycEmailAddress</td><td>String</td><td>N</td><td><a href="mailto:john.doe@example.com">john.doe@example.com</a></td><td>Borrower Email address</td></tr><tr><td>kycAddress</td><td>String</td><td>N</td><td>123 Main St, Anytown, USA</td><td>Borrower Address</td></tr><tr><td>loanInfoLoanType</td><td>Int</td><td>Y</td><td>1</td><td>0 - Other<br>1 - PayDayLoan<br>2 - POS<br>3 - CashLoan<br>4 - CreditLine<br>5 - CreditCard<br>6 - AutoLoan<br>7 - MotorcycleLoan<br>8 - HomeLoan</td></tr><tr><td>loanInfoApplicationDate</td><td>Date</td><td>Y</td><td>2022-01-01</td><td>Loan Application date</td></tr><tr><td>loanInfoOpenDate</td><td>Date</td><td>Y</td><td>2022-01-01</td><td>Loan Open date</td></tr><tr><td>loanInfoLoanTerm</td><td>Int</td><td>Y</td><td>5</td><td>Count of months, loan term.</td></tr><tr><td>loanInfoOpenBalance</td><td>Float</td><td>Y</td><td>10000</td><td>Loan Open Balance</td></tr><tr><td>loanInfoOutstandingBalance</td><td>Float  </td><td>Y</td><td>8000</td><td>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</td></tr><tr><td>loanInfoNextDueDate</td><td>Date</td><td>Y</td><td>2024-05-01</td><td>Loan Next Due date</td></tr><tr><td>loanInfoStatusCode</td><td>String</td><td>Y</td><td>Active</td><td>Active, Delayed, Collection, Written off, Closed, Rejected, Incomplete, Not Disbursed</td></tr><tr><td>loanInfoInstallmentAmount</td><td>Float</td><td>Y</td><td>500</td><td>Loan installment amount</td></tr><tr><td>loanInfoOverdueAmount</td><td>Float</td><td>Y</td><td>100</td><td>Loan Overdue amount</td></tr><tr><td>loanInfoRepaymentFrequency</td><td>Int</td><td>Y</td><td>1</td><td>0 - Other<br>1 - Monthly<br>2 - Biweekly<br>3 - SinglePayment</td></tr><tr><td>loanInfoRepaymentFullHistory</td><td>Array of Objects</td><td>Y</td><td> { "dueDate": "2024-03-15", "paymentDate": "2024-03-15",  "paymentAmount": 1300.00 },<br> {"dueDate": "2024-04-15", "paymentDate": "2024-04-15", "paymentAmount": 1250.50},<br> {"dueDate": "2024-05-15", "paymentDate": "2024-05-15","paymentAmount": 1275.75 },<br> { "dueDate": "2024-06-15", "paymentDate": "2024-06-15", "paymentAmount": 1320.25 },<br> {"dueDate": "2024-07-15","paymentDate": "2024-07-15","paymentAmount": 1295.00}<br></td><td>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.</td></tr><tr><td>loanInfoCloseDate</td><td>Date</td><td>Y</td><td>2024-05-25</td><td>Loan Close Date</td></tr></tbody></table>

{% hint style="success" %} <mark style="background-color:green;">Detailed descriptions for the variables can be found here</mark> [<mark style="background-color:green;">https://docs.google.com/spreadsheets/d/1ChI0ldz1yBr1bRYjZ6PeuXNahE0kwWyN/edit?usp=drivesdk\&ouid=102629089778994761174\&rtpof=true\&sd=true</mark>](https://docs.google.com/spreadsheets/d/1ChI0ldz1yBr1bRYjZ6PeuXNahE0kwWyN/edit?usp=drivesdk\&ouid=102629089778994761174\&rtpof=true\&sd=true)
{% endhint %}

<figure><img src="https://2535431771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA6bXF0ByrsIRc0FWtxRe%2Fuploads%2Fv6WBRj8q3BSl8GP0Dxme%2FSlide5.jpg?alt=media&#x26;token=af79a5eb-02ed-4c7e-b23e-085e24698bbd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The API structure below is just an example. Every contributor can make the endpoint in their own way.
{% endhint %}

### 3. Create automation to upload your new hashed phones on a daily basis following this procedure [submitting-phone-numbers](https://docs.lenderlink.ph/product-guides/submitting-phone-numbers "mention")

### 4.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**

1. The structure of the Contributor Database table to be used as a layout for the API response.
2. The contributors should keep the data, which will be returned to LendeLink upon enquiry, up-to-date.
3. 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.&#x20;

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 that **uses the POST method** and accepts a request body containing the parameters listed below. The endpoint must return a detailed response containing KYC and loan information.

**Example API Endpoint**

* POST API URL (Endpoint)

```
https://somedomain.com/api/v1/borrower
```

* Request Headers

  * `Content-Type: application/json`
  * `Authorization: Token <token>`

* Multi Parameters Search Query :

{% hint style="success" %}
A Multiple parameters search should be implemented. LenderLink will send API calls containing all the parameters below. &#x20;
{% endhint %}

<table><thead><tr><th width="258">Parameter</th><th width="125">Type</th><th width="149.95703125">Required</th><th>Description</th></tr></thead><tbody><tr><td>requestId</td><td>String</td><td>Yes</td><td>Unique identification code generated by the client</td></tr><tr><td>firstName</td><td>String</td><td>Yes</td><td>First Name</td></tr><tr><td>lastName</td><td>String</td><td>Yes</td><td>Last Name</td></tr><tr><td>dateOfBirth</td><td>Date</td><td>Yes</td><td>Date of Birth - YYYY-MM-DD</td></tr><tr><td>cellphoneNumber</td><td>String</td><td>Yes</td><td>Borrower's phone number, the format is 63XXXXXXXXXX.</td></tr><tr><td>email</td><td>String</td><td>Optional</td><td>Borrower's email address</td></tr><tr><td>idNumber</td><td>String</td><td>Optional</td><td>Borrower's ID document number. ID, Driver license, etc</td></tr></tbody></table>

* Example JSON of a request to the API

```json
{
  "requestId": "X123-AB45",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-01",
  "cellphoneNumber": "639170000001",
  "email": "john.doe@example.com",
  "idNumber": "ABC123456"
}
```

\
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.&#x20;

#### Example of proper usage:&#x20;

```sql
SELECT *
FROM db_table
WHERE mobilePhone = '639170000001'
OR email = 'john.doe@example.com'
OR (firstName = 'John' AND lastName = 'Doe' AND dateOfBirth = '1990-01-01');
```

#### Here is example of improper usage:

```sql
SELECT *
FROM db_table
WHERE mobilePhone = '639170000001'
OR email = 'john.doe@example.com'
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.&#x20;

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.&#x20;

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.&#x20;

Example response:&#x20;

* Success Response

```json
{ 
  "mobilePhone":[
    {
      "recordId": "c1c9f6a3-0f1d-4f62-9d2d-8b8b8f1a2d7e",
      "kycSurname": "Doe",
      "kycFirstName": "John",
      "kycMiddleName": "Smith",
      "kycDateOfBirth": "1990-01-01",
      "kycIdNumber": "ABC123456",
      "kycIdType": 4,
      "kycMobileNumber": "639170000001",
      "kycEmailAddress": "john.doe@example.com",
      "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",
      "loanInfoRepaymentFullHistory": [
        {
          "dueDate": "2024-03-15",
          "paymentDate": "2024-03-15",
          "paymentAmount": 1300.00
        },
        {
          "dueDate": "2024-04-15",
          "paymentDate": "2024-04-15",
          "paymentAmount": 1250.50
        },
        {
          "dueDate": "2024-05-15",
          "paymentDate": "2024-05-15",
          "paymentAmount": 1275.75
        },
        {
          "dueDate": "2024-06-15",
          "paymentDate": "2024-06-15",
          "paymentAmount": 1320.25
        },
        {
          "dueDate": "2024-06-15",
          "paymentDate": "15-07-2024",
          "paymentAmount": 1295.00
        }
      ]
    }
  ],
  "firstNamelastNamedateOfBirth": [
    {
      "recordId": "7f2c1b7a-9c55-4f67-8b2a-2c8d30f5c9c1",
      "kycSurname": "Doe",
      "kycFirstName": "John",
      "kycMiddleName": "Smith",
      "kycDateOfBirth": "1990-01-01",
      "kycIdNumber": "ABC123456",
      "kycIdType": 4,
      "kycMobileNumber": "639170000001",
      "kycEmailAddress": "john.doe@example.com",
      "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",
      "loanInfoRepaymentFullHistory": [
        {
          "dueDate": "2024-03-15",
          "paymentDate": "2024-03-15",
          "paymentAmount": 1300.00
        },
        {
          "dueDate": "2024-04-15",
          "paymentDate": "2024-04-15",
          "paymentAmount": 1250.50
        },
        {
          "dueDate": "2024-05-15",
          "paymentDate": "2024-05-15",
          "paymentAmount": 1275.75
        },
        {
          "dueDate": "2024-06-15",
          "paymentDate": "2024-06-15",
          "paymentAmount": 1320.25
        },
        {
          "dueDate": "2024-07-15",
          "paymentDate": "2024-07-15",
          "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).

{% hint style="warning" %}
For  loanInfoStatusCode: "Rejected" , when you encounter a rejected borrower, you should return an object similar to the one below. But in the structure above.
{% endhint %}

```json
{
    "recordId": "2a6f3d5e-6b2c-4b8b-a3c0-9e1a4c7d2f11",
    "kycSurname": "Doe",
    "kycFirstName": "John",
    "kycMiddleName": "Smith",
    "kycDateOfBirth": "1990-01-01",
    "kycIdNumber": "ABC123456",
    "kycIdType": 4,
    "kycMobileNumber": "639123456789",
    "kycEmailAddress": "john.doe@example.com",
    "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
}
```

### 5. Follow [submitting-phone-numbers](https://docs.lenderlink.ph/product-guides/submitting-phone-numbers "mention") as a final step.

### 6.Backup option

If the contributor is not API ready yet as a backup option we can use a SFTP integration as described below.

<figure><img src="https://2535431771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA6bXF0ByrsIRc0FWtxRe%2Fuploads%2F5QSoOx0ItwbBdqbLN6nZ%2FSlide2.jpg?alt=media&#x26;token=bc1ece6a-c2aa-4e42-b3d5-10ca1a1de2b0" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2535431771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FA6bXF0ByrsIRc0FWtxRe%2Fuploads%2FkbCKzMV9F4ITVKoV8Qso%2FSlide3.jpg?alt=media&#x26;token=b39d3d70-3465-49ea-a250-5e0370e59773" alt=""><figcaption></figcaption></figure>