projects.apps.borrowers

Overview

A borrower is an individual or company user account that can use lending services offered on a lending app. The Borrowers API allows you to do the following.

  • List, create and manage borrowers.

  • Request for all product offers that a borrower qualifies for.

  • Preview loan contracts for product offers.

{
   "borrowerId": string,
   "category": string,
   "startDate": string,
   "status": number,
   "borrowerNo": number,
   "individual": object(Individual) | null,
   "company": object(Company) | null,
   "devices": [
      {
         object(Device)
      }
   ],
   "loans": [
      {
         object(LoanSummary)
      }
   ],
   "settings": {
       string: string,
       ...
    },
   "profiles": object(BorrowerProfiles) | null
}

Fields

List

GET https://lending.wezaapis.com/v1/projects/{projectId}/apps/{appId}/borrowers

Path Parameters

Query Parameters

Headers

Request Body

The request body should be empty.

Response Body

If successful, the response will contain data with the following structure.

{
  "borrowers": [
    {
      object(Borrower)
    }
  ],
  "nextPageToken": string,
}

Fields

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:read

The authenticated user must have the lending.borrowers.list permission.

Create

POST https://lending.wezaapis.com/v1/projects/{projectId}/apps/{appId}/borrowers

Create a borrower if one doesn’t exist. Note that this method will throw a 409 HTTP error if you try to create an already existing borrower. See the Errors section for more details.

Path Parameters

Headers

{
   "borrowerId": string,
   "startDate": string,
   "status": string,
   "borrowerNo": number,
   "identity": object(Identity),
   "demographic": object(Demographic),
   "devices": [
      {
         object(Device)
      }
   ],
   "loans": [
      {
         object(Loan)
      }
   ],
   "settings": {
       string: string,
       ...
    }
}

Request Body

The request body contains an instance of Borrower.

Response Body

The response body contains a new instance of Borrower.

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.borrowers.create permission.

Example


curl -X POST \
https://lending.wezaapis.com/v1/projects/:projectId/apps/testapp/borrowers \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer validtestauthtoken' \
-d '{
	"borrowerId": "10023",
	"category": "individual",
	"startDate": "2019-05-12T12:00:00+03:00",
	"individual": {
		"surname": "Garvey",
    	"othernames": "Marcus Mosiah",
    	"dateOfBirth": "1980-01-01",
    	"sex": "male",
    	"governmentIdNo": "100000",
    	"countryOfResidence": "Kenya",
    	"emailAddress": "marcus.garvey@hotmail.com",
    	"phoneNumber": "+254700000010",
			"employmentStatus": "self-employed",
    	"maritalStatus": "single",
    	"educationLevel": "college",
    	"noOfDependants": 1
    },
	"devices": [{
		"deviceId": "11103",
		"deviceType": "mobile_phone",
		"modelNumber": "SM-J400F",
		"osName": "android",
		"createdAt": "2019-05-12T12:00:55+03:00",
		"active": true,
		"equipmentId": "1000000000000",
		"otherEquipmentId": "1000000000001",
		"osVersion": "9"
	}],
	"loans": [
		{
			"loanId": "201911",
			"principalAmount": 1000,
			"payableAmount": 1256,
			"paidAmount": 1256,
			"startDate": "2019-05-12T12:00:00+03:00",
			"endDate": "2019-06-12T12:00:00+03:00",
			"nextPaymentDate": null,
			"completionDate": "2019-06-12T10:00:00+03:00",
			"assessmentId": null
		},
		{
			"loanId": "211311",
			"principalAmount": 1000,
			"payableAmount": 1256,
			"paidAmount": 0,
			"startDate": "2019-07-12T12:00:00+03:00",
			"endDate": "2019-08-12T12:00:00+03:00",
			"nextPaymentDate": "2019-08-12T12:00:00+03:00",
			"completionDate": null,
			"assessmentId": null
		}
	],
	"settings": {
		"timezone": "Africa/Nairobi"
	}
}'

Get

GET https://lending.wezaapis.com/v1/projects/{projectId}/apps/{appId}/borrowers/{borrowerId}

Get an existing borrower. This method will throw a 404 HTTP error if you try to access an invalid borrower resource. See the Errors section for more details.

Path Parameters

Headers

{
   "borrowerId": string,
   "startDate": string,
   "status": string,
   "borrowerNo": number,
   "identity": object(Identity),
   "demographic": object(Demographic),
   "devices": [
      {
         object(Device)
      }
   ],
   "loans": [
      {
         object(Loan)
      }
   ],
   "settings": {
       string: string,
       ...
    }
}

Request Body

The request body should be empty.

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:read

The authenticated user must have the lending.borrowers.get permission.

Examples

curl -X GET \
https://lending.wezaapis.com/v1/projects/test-project/apps/testapp/borrowers/10023 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer validtestauthtoken' \

Patch

PATCH https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/borrowers/:borrowerId

Updates an existing borrower account. Note that this method will throw a 404 HTTP error if you try to patch an invalid borrower resource. See the Errors section for more details.

Path Parameters

Headers

{
   "borrowerId": string,
   "startDate": string,
   "status": string,
   "borrowerNo": number,
   "identity": object(Identity),
   "demographic": object(Demographic),
   "devices": [
      {
         object(Device)
      }
   ],
   "loans": [
      {
         object(Loan)
      }
   ],
   "settings": {
       string: string,
       ...
    }
}

Request Body

The request body should contain at least one of the following parameters.

Response Body

The response body contains a new instance of Borrower.

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.borrowers.patch permission.

Examples

curl -X PATCH \
https://lending.wezaapis.com/v1/projects/test-project/apps/testapp/borrowers/10023 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer validtestauthtoken' \
-d '{
	"devices": [
        {
            "deviceId": "11103",
            "deviceType": "mobile_phone",
            "modelNumber": "SM-J400F",
            "osName": "android",
            "createdAt": "2019-05-12T12:00:55+03:00",
            "active": false,
            "osVersion": "8"
        },
        {
            "deviceId": "12103",
            "deviceType": "mobile_phone",
            "modelNumber": "SM-J400F",
            "osName": "android",
            "createdAt": "2019-12-01T12:00:55+03:00",
            "active": true,
            "osVersion": "9"
        }
    ],
    "loans": [
        {
            "loanId": "78777ae3-6d10-45dd-afc4-5a59fba02f5f",
            "principalAmount": 1000,
            "payableAmount": 1131,
            "paidAmount": 1131,
            "startDate": "2019-11-09T21:00:00.000Z",
            "endDate": "2019-12-09T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-11-14T21:00:00.000Z",
            "assessmentId": "199ce353-9646-5a39-9c20-6c0b8e2889b8"
        },
        {
            "loanId": "f19513f1-2155-4d5c-858d-50c640cea34d",
            "principalAmount": 1250,
            "payableAmount": 1413,
            "paidAmount": 1414,
            "startDate": "2019-11-14T21:00:00.000Z",
            "endDate": "2019-12-14T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-12-11T21:00:00.000Z",
            "assessmentId": "2cb3a0d3-a429-550b-a97e-60de17e01222"
        },
        {
            "loanId": "ca5b78bc-3318-4d2b-9e52-8d5cb4828be4",
            "principalAmount": 1500,
            "payableAmount": 1670,
            "paidAmount": 1670,
            "startDate": "2019-12-12T21:00:00.000Z",
            "endDate": "2020-01-02T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-12-26T21:00:00.000Z",
            "assessmentId": "25a739d6-1def-5e56-866c-0bf7d87a8bf8"
        },
        {
            "loanId": "aebde33f-877e-4a06-93b5-b0b22e852e65",
            "principalAmount": 1500,
            "payableAmount": 1696,
            "paidAmount": 1696,
            "startDate": "2019-12-29T21:00:00.000Z",
            "endDate": "2020-01-28T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2020-01-30T21:00:00.000Z",
            "assessmentId": "a27843d9-aed1-5425-b6ab-661336cefe09"
        },
        {
            "loanId": "d7064d37-e021-4730-85ff-5f18a4463550",
            "principalAmount": 1500,
            "payableAmount": 1696,
            "paidAmount": 1696,
            "startDate": "2020-01-31T21:00:00.000Z",
            "endDate": "2020-03-01T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2020-03-01T21:00:00.000Z",
            "assessmentId": "8e4d3b7e-3314-5fa6-955f-6af9ffd1a40a"
        },
        {
            "loanId": "a13c21dc-a7a8-400a-aeb4-93ac99ddb844",
            "principalAmount": 1500,
            "payableAmount": 1692,
            "paidAmount": 1692,
            "startDate": "2020-03-01T21:00:00.000Z",
            "endDate": "2020-03-31T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2020-03-30T21:00:00.000Z",
            "assessmentId": "5a340cf4-7528-56fa-af16-978cb0bf2208"
        },
        {
            "loanId": "41e9a6e4-6d4e-4fef-acb4-568fb62ea372",
            "principalAmount": 1500,
            "payableAmount": 1692,
            "paidAmount": 0,
            "startDate": "2020-04-02T21:00:00.000Z",
            "endDate": "2020-05-02T21:00:00.000Z",
            "nextPaymentDate": "2020-05-02T21:00:00.000Z",
            "completionDate": null,
            "assessmentId": "b56e23fb-324b-5f3f-9bcb-e588767504fe"
        }
    ],
    "settings": {
        "timezone": "Africa/Nairobi"
    }
}'

{
    "uid": "58c41651-72f2-5217-b774-471b083739aa",
    "name": "projects/test-project/apps/testapp/borrowers/10023",
    "status": 0,
    "createdAt": "2020-06-23T18:33:32.381Z",
    "borrowerId": "10023",
    "startDate": "2019-05-12T09:00:00.000Z",
    "category": "individual",
    "borrowerNo": 2576645010869,
    "individual": {
        "surname": "GARVEY",
        "othernames": "MARCUS MOSIAH",
        "dateOfBirth": "1980-01-01",
        "sex": "male",
        "governmentIdNo": "100000",
        "countryOfResidence": "Kenya",
        "emailAddress": "marcus.garvey@hotmail.com",
        "phoneNumber": "+254700000010",
        "employmentStatus": "self-employed",
        "maritalStatus": "single",
        "educationLevel": "college",
        "noOfDependants": 1,
        "fingerprints": [],
        "photos": []
    },
    "company": null,
    "devices": [
        {
            "deviceId": "11103",
            "deviceType": "mobile_phone",
            "modelNumber": "SM-J400F",
            "osName": "android",
            "createdAt": "2019-05-12T09:00:55.000Z",
            "active": false,
            "osVersion": "8",
            "serialNumber": null,
            "equipmentId": null,
            "otherEquipmentId": null
        },
        {
            "deviceId": "12103",
            "deviceType": "mobile_phone",
            "modelNumber": "SM-J400F",
            "osName": "android",
            "createdAt": "2019-12-01T09:00:55.000Z",
            "active": true,
            "osVersion": "9",
            "serialNumber": null,
            "equipmentId": null,
            "otherEquipmentId": null
        }
    ],
    "loans": [
        {
            "loanId": "78777ae3-6d10-45dd-afc4-5a59fba02f5f",
            "principalAmount": 1000,
            "payableAmount": 1131,
            "paidAmount": 1131,
            "startDate": "2019-11-09T21:00:00.000Z",
            "endDate": "2019-12-09T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-11-14T21:00:00.000Z",
            "assessmentId": "199ce353-9646-5a39-9c20-6c0b8e2889b8"
        },
        {
            "loanId": "f19513f1-2155-4d5c-858d-50c640cea34d",
            "principalAmount": 1250,
            "payableAmount": 1413,
            "paidAmount": 1414,
            "startDate": "2019-11-14T21:00:00.000Z",
            "endDate": "2019-12-14T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-12-11T21:00:00.000Z",
            "assessmentId": "2cb3a0d3-a429-550b-a97e-60de17e01222"
        },
        {
            "loanId": "ca5b78bc-3318-4d2b-9e52-8d5cb4828be4",
            "principalAmount": 1500,
            "payableAmount": 1670,
            "paidAmount": 1670,
            "startDate": "2019-12-12T21:00:00.000Z",
            "endDate": "2020-01-02T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-12-26T21:00:00.000Z",
            "assessmentId": "25a739d6-1def-5e56-866c-0bf7d87a8bf8"
        },
        {
            "loanId": "aebde33f-877e-4a06-93b5-b0b22e852e65",
            "principalAmount": 1500,
            "payableAmount": 1696,
            "paidAmount": 1696,
            "startDate": "2019-12-29T21:00:00.000Z",
            "endDate": "2020-01-28T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2020-01-30T21:00:00.000Z",
            "assessmentId": "a27843d9-aed1-5425-b6ab-661336cefe09"
        },
        {
            "loanId": "d7064d37-e021-4730-85ff-5f18a4463550",
            "principalAmount": 1500,
            "payableAmount": 1696,
            "paidAmount": 1696,
            "startDate": "2020-01-31T21:00:00.000Z",
            "endDate": "2020-03-01T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2020-03-01T21:00:00.000Z",
            "assessmentId": "8e4d3b7e-3314-5fa6-955f-6af9ffd1a40a"
        },
        {
            "loanId": "a13c21dc-a7a8-400a-aeb4-93ac99ddb844",
            "principalAmount": 1500,
            "payableAmount": 1692,
            "paidAmount": 1692,
            "startDate": "2020-03-01T21:00:00.000Z",
            "endDate": "2020-03-31T21:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2020-03-30T21:00:00.000Z",
            "assessmentId": "5a340cf4-7528-56fa-af16-978cb0bf2208"
        },
        {
            "loanId": "41e9a6e4-6d4e-4fef-acb4-568fb62ea372",
            "principalAmount": 1500,
            "payableAmount": 1692,
            "paidAmount": 0,
            "startDate": "2020-04-02T21:00:00.000Z",
            "endDate": "2020-05-02T21:00:00.000Z",
            "nextPaymentDate": "2020-05-02T21:00:00.000Z",
            "completionDate": null,
            "assessmentId": "b56e23fb-324b-5f3f-9bcb-e588767504fe"
        }
    ],
    "settings": {
        "timezone": "Africa/Nairobi"
    }
}

Delete

DELETE https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/borrowers/:borrowerId

Delete an existing borrower account.

Path Parameters

Headers

Request Body

The request body should be empty.

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.borrowers.delete permission.

GetOffers

POST https://lending.wezaapis.com/v1/projects/{projectId}/apps/{appId}/borrowers/{borrowerId}:getOffers

Request for a summary of all lending product offers that a borrower qualifies for. You can read more about the loan underwriting process here. This is a long running operation which is processed in the background and as such, the client would need to make a second call to this method later so as to retrieve the result. Under normal conditions, this operation would take a maximum of 120 seconds to complete.

Path Parameters

Headers

# Creating the request operation

## Request

curl --request POST 'https://lending.wezaapis.com/v1/projects/test-project/apps/testapp/borrowers/10023/getOffers' \
--header 'Authorization: Bearer validauthtoken' \
--header 'Content-Type: application/json' \
--data-raw '{
    "assessmentType": "assessmentTypes/personal_credit_standard",
    "timestamp": "2020-09-28T12:00:00Z",
    "requestId": "bc9ee1bcb9"
}'

## Response

{
    "name": "operations/6142027d-3c3d-5142-8ba3-2e219e67d6fe",
    "operationId": "6142027d-3c3d-5142-8ba3-2e219e67d6fe",
    "done": false,
    "metadata": {
        "status": "queued",
        "startTime": "2020-09-22T16:54:54.102Z",
        "endTime": null,
        "expiryTime": "2020-10-22T16:54:54.102Z",
        "projectId": "test-project",
        "appId": "testapp",
        "accountId": "borrower:10023",
        "requestId": "75076298bb",
        "assessmentId": "81693e42-9be3-506f-8d8c-b192f30c69db"
    },
    "result": null
}


# Retrieving the operation result

## Request

curl --request POST 'https://lending.wezaapis.com/v1/projects/test-project/apps/testapp/borrowers/10023/getOffers' \
--header 'Authorization: Bearer validauthtoken' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requestId": "75076298bb"
}'

## Response

{
    "name": "operations/f90044c0-2dcb-5358-a167-1b1fde5c93c0",
    "operationId": "f90044c0-2dcb-5358-a167-1b1fde5c93c0",
    "done": true,
    "metadata": {
        "status": "completed",
        "startTime": "2020-09-22T16:54:54.102Z",
        "endTime": "2020-09-22T16:59:23.000Z",
        "expiryTime": "2020-10-22T16:54:54.102Z",
        "projectId": "test-project",
        "appId": "testapp",
        "accountId": "borrower:10023",
        "requestId": "75076298bb",
        "assessmentId": "81693e42-9be3-506f-8d8c-b192f30c69db"
    },
    "result": {
        "error": null,
        "response": {
            "creditLimit": 1000,
            "products": [
                {
                    "productId": "30_day_loan_1_repayment",
                    "terms": {
                        "interest": {
                            "riskPremiumRate": 0.18
                        }
                    }
                },
                {
                    "productId": "21_day_loan_3_repayments",
                    "terms": {
                        "interest": {
                            "riskPremiumRate": 0.16
                        }
                    }
                }
            ],
            "interestRateWaiver": 0,
            "validFrom": "2020-09-22T16:59:22.891Z"
        }
    }
}

Request Body

The request body should contain at least one of the following parameters.

Response Body

The response body contains an instance of GetOffersResponse.

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.borrowers.getOffers permission.

GetOffersContracts

POST https://lending.wezaapis.com/v1/projects/{projectId}/apps/{appId}/borrowers/{borrowerId}:getOfferContracts

Returns a preview of loan contract details for all products within a loan offer summary for a specified loan amount and/or start date. You can read more about this in the loan underwriting process here.

Path Parameters

Headers


## Request

curl --request POST 'https://lending.wezaapis.com/v1/projects/test-project/apps/testapp/borrowers/10023/getOfferContracts' \
--header 'Authorization: Bearer validauthtoken' \
--header 'Content-Type: application/json' \
--data-raw '{
    "offerSummary": {
        "creditLimit": 1000,
        "products": [
            {
                "productId": "30_day_loan_1_repayment",
                "terms": {
                    "interest": {
                        "riskPremiumRate": 0.13
                    }
                }
            }
        ],
        "interestRateWaiver": 0
    },
    "amount": 1000,
    "startDate": "2020-09-19T00:00:00Z"
}'

## Response

[
    {
        "versionNo": 1,
        "productId": "30_day_loan_1_repayment",
        "terms": {
            "fees": [
                {
                    "kind": "deducted_disbursement_fee",
                    "value": 0.02,
                    "required": true,
                    "description": "Origination fee of 2% of the loan principal amount.",
                    "displayName": "2% Origination Fee",
                    "calculationMethod": "principal_amount_ratio",
                    "installmentTarget": "first_in_sequence",
                    "calculateInAdvance": true
                },
                {
                    "kind": "late_payment_fee",
                    "value": 0.02,
                    "required": true,
                    "description": "A fee of 2% of the loan principal amount that is charged when an installment payment is late.",
                    "displayName": "2% Late Payment Fee",
                    "calculationMethod": "principal_amount_ratio",
                    "installmentTarget": "in_progress",
                    "calculateInAdvance": false
                }
            ],
            "period": "30 days",
            "penalty": {
                "rate": 0.02,
                "gracePeriod": "2 days",
                "calculationMethod": "overdue_principal"
            },
            "interest": {
                "maxAER": 15,
                "maxAPR": 15,
                "baseRate": 0.15,
                "waiverRate": 0,
                "riskPremiumRate": 0.13,
                "calculationMethod": "reducing_balance",
                "compoundingPeriod": "30 days"
            }
        },
        "amounts": {
            "requested": 1000,
            "disbursement": 980,
            "principal": 1000,
            "interest": 23,
            "repayment": 1043,
            "fees": 20,
            "penalty": 0
        },
        "interestRates": {
            "nominalRate": 0.28,
            "periodicRate": 0.023,
            "APR": 0.5232,
            "AER": 0.3189,
            "APY": 0.3189
        },
        "startDate": "2020-09-19T00:00:00.000Z",
        "maturityDate": "2020-10-19T23:59:59.999Z",
        "adjustments": [
            {
                "kind": "deducted_disbursement_fee",
                "displayName": "2% Origination Fee",
                "description": "Origination fee of 2% of the loan principal amount.",
                "target": "disbursement",
                "action": "deduct",
                "valueType": "absolute",
                "value": 20,
                "source": "principal"
            }
        ],
        "tranches": [
            {
                "sequenceNo": 1,
                "startDate": "2020-09-19T00:00:00.000Z",
                "dueDate": "2020-09-19T23:59:59.999Z",
                "amount": 980
            }
        ],
        "installments": [
            {
                "sequenceNo": 1,
                "startDate": "2020-09-19T00:00:00.000Z",
                "dueDate": "2020-10-19T23:59:59.999Z",
                "amounts": {
                    "repayment": 1043,
                    "principal": 1000,
                    "interest": 23,
                    "fees": 20,
                    "penalty": 0
                }
            }
        ]
    }
]

Request Body

The request body should contain the following parameters.

Response Body

The response body contains an array of LendingContract instances.

Authorization

Requires any one of the following OAuth scopes:

  • platform

  • platform.lending

  • platform.lending:read

The authenticated user must have the lending.borrowers.getOfferContracts permission.

Last updated