Using Credit Assessments

Overview

Credit assessments give you a real time credit rating and credit score for a borrower registered on your lending application. This guide aims to demonstrate how to do a deep integration to the Weza.io Lending APIs on your application so that you can start using credit assessments.

Prerequisites

To use the Lending APIs, you will require the following.

You can setup your organization, project, API credentials and lending app (and much more) using our web dashboard at dashboard.weza.io. You can reach out to the weza technical team on our developer slack if you encounter any problems.

  1. A valid weza.io project with billing enabled and the Lending API activated.

  2. Valid weza.io API client credentials. See the authentication section on how to perform authenticate and authorize requests on weza.io. The authorizing user should have the Lending App Admin role.

  3. A valid weza.io Lending App.

  4. One or more users who are requesting for loans (borrowers) from an Android device.

  5. SMS texts and phone contacts for each user. SMS texts have to be from within the last 6 months.

  6. A server that can communicate with weza.io APIs. If your lending application is hosted on a server, then this is enough.

Send Requests

For our use case, let us assume we want to get an instant personal credit assessment whenever someone requests for a loan on our lending app. We will need to perform the following actions using the Lending APIs.

  • Create borrower account.

  • Update borrower account.

  • Create borrower events.

  • Create and retrieve borrower assessment

Let's look at each in detail.

Create Borrower Account

A borrower is an individual or company account that can apply and receive loans on a lending app.

When a borrower creates an account on your app, you will need to register them on the platform using the apps.borrowers.create API method.

Refer to the Borrowers API reference for further details.

Loan data is not immediately needed at the time of account creation, but you should send any existing historical data for the account.

All PII is encrypted before we save it to our servers.

Example

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

Create a borrower on a lending app

Path Parameters

NameTypeDescription

appId

string

application name

projectId

string

random-chars-191382

Headers

NameTypeDescription

Content-Type

string

application/json

{
    "uid": "58c41651-72f2-5217-b774-471b083739aa",
    "name": "projects/random-chars-191382/apps/loanbee/borrowers/10023",
    "status": 0,
    "createdAt": "2020-06-23T18:30:00.003Z",
    "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": true,
            "equipmentId": "1000000000000",
            "otherEquipmentId": "1000000000001",
            "osVersion": "9",
            "serialNumber": null
        }
    ],
    "loans": [
        {
            "loanId": "201911",
            "principalAmount": 1000,
            "payableAmount": 1256,
            "paidAmount": 1256,
            "startDate": "2019-05-12T09:00:00.000Z",
            "endDate": "2019-06-12T09:00:00.000Z",
            "nextPaymentDate": null,
            "completionDate": "2019-06-12T07:00:00.000Z",
            "assessmentId": null
        },
        {
            "loanId": "211311",
            "principalAmount": 1000,
            "payableAmount": 1256,
            "paidAmount": 0,
            "startDate": "2019-07-12T09:00:00.000Z",
            "endDate": "2019-08-12T09:00:00.000Z",
            "nextPaymentDate": "2019-08-12T09:00:00.000Z",
            "completionDate": null,
            "assessmentId": null
        }
    ],
    "settings": {
        "timezone": "Africa/Nairobi"
    }
}
{
	"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"
	}
}

Update Borrower Account

Whenever any device or loan or settings information is updated for a borrower, you will need to send the updated list of devices and loans and/or settings using the apps.borrowers.patch method.

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

Patch a borrower account

Path Parameters

NameTypeDescription

borrowerId

string

Borrower Id

appId

string

Application Id

projectId

string

Random Characters

{
    "uid": "58c41651-72f2-5217-b774-471b083739aa",
    "name": "projects/random-chars-191382/apps/loanbee/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
        }
    ],
    "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": 1256,
    			"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": "2019-08-11T12:00:00+03:00",
    			"assessmentId": "41e9a6e4-6d4e-4fef-acb4-568fb62ea372"
    		},
        {
    			"loanId": "212400",
    			"principalAmount": 1000,
    			"payableAmount": 1256,
    			"paidAmount": 0,
    			"startDate": "2019-08-12T12:00:00+03:00",
    			"endDate": "2019-09-12T12:00:00+03:00",
    			"nextPaymentDate": "2019-09-12T12:00:00+03:00",
    			"completionDate": null,
    			"assessmentId": null
    		}
    ],
    "settings": {
        "timezone": "Africa/Nairobi"
    }
}
{
    "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": 1256,
    			"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": "2019-08-11T12:00:00+03:00",
    			"assessmentId": "41e9a6e4-6d4e-4fef-acb4-568fb62ea372"
    		},
        {
    			"loanId": "212400",
    			"principalAmount": 1000,
    			"payableAmount": 1256,
    			"paidAmount": 0,
    			"startDate": "2019-08-12T12:00:00+03:00",
    			"endDate": "2019-09-12T12:00:00+03:00",
    			"nextPaymentDate": "2019-09-12T12:00:00+03:00",
    			"completionDate": null,
    			"assessmentId": null
    		}
    ]
}

Send Personal Data

Whenever you receive lending data from the user, you will need to send it to weza.io by creating a personal_data.received event using the apps.events.create API method. All PII is encrypted before we save it to our servers.

Keep in mind to send data that is only less than 5 MB in size.

Make sure reporting of user data happens regularly for each borrower or you will not get successful assessments. Most assessments will need data from the past 6 months of the assessment timestamp.

POST https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/events

Path Parameters

NameTypeDescription

appId

string

Application ID

projectId

string

Project ID

Headers

NameTypeDescription

Content-Type

string

application/json

{
  "name": "projects/test-project/apps/test-app/events/Ym9ycm93ZXI6MTAwMjM7cGVyc29uYWxfZGF0YS5jYXB0dXJlZDsxNTE0Nzk3MjAwMDAw",
  "uid": "424c79ae-0d78-57d1-93c0-6dadc068858b",
  "status": 1,
  "createdAt": "2020-03-09T09:34:09.727Z",
  "eventId": "Ym9ycm93ZXI6MTAwMjM7cGVyc29uYWxfZGF0YS5jYXB0dXJlZDsxNTE0Nzk3MjAwMDAw",
  "accountId": "borrower:10023",
  "eventType": "personal_data.captured",
  "timestamp": "2018-01-01T09:00:00.000Z",
  "appVersionId": "v1",
  "data": [
    {
      "kind": "lending.wezaapis.com/sms",
      "values": [
        {
          "address": "MPESA",
          "direction": "inbound",
          "smsId": "2352",
          "read": true,
          "timestamp": 1574620292034,
          "rawBody": "unEncryptedSMS"
        },
        {
          "address": "MPESA",
          "direction": "inbound",
          "smsId": "2352",
          "read": true,
          "timestamp": 1574620766564,
          "rawBody": "unEcryptedSMS"
        }
      ]
    },
    {
      "kind": "lending.wezaapis.com/device/battery",
      "values": [
        {
          "timestamp": 1574620292034,
          "isCharging": true,
          "chargingMethod": "AC",
          "level": 60
        }
      ]
    },
    {
      "kind": "lending.wezaapis.com/device/location",
      "values": [
        {
          "timestamp": 1574620292034,
          "latLng": ""
        }
      ]
    },
    {
      "kind": "lending.wezaapis.com/device/app",
      "values": [
        {
          "timestamp": 1574620292034,
          "name": "",
          "package": "",
          "label": ""
        }
      ]
    }
  ],
  "result": null
}
{
	"accountId": "borrower:10023",
    "eventType": "personal_data.captured",
    "timestamp": "2020-03-11T12:00:00+03:00",
    "data": [
        {
            "kind": "lending.wezaapis.com/contact",
            "values": [
                {
                    "name": "William DuBois",
                    "primaryAddress": { "addressName": "+254 722034142", "addressType": "telephone" },
                    "otherAddresses": [
                        { "addressName": "+(254)733-034-142", "addressType": "telephone" },
                        { "addressName": "william.dubois@gmail.com", "addressType": "email" }
                    ]
                }
            ]
        },
        {
            "kind": "lending.wezaapis.com/sms",
            "values": [
                {
                    "address": "MPESA",
                    "direction": "inbound",
                    "timestamp": 1576222666000,
                    "rawBody": "NLD3MRV89V Confirmed. On 13/12/19 at 10:37 AM Give Ksh8,000.00 cash to Technology House Ltd Village Market New M-PESA balance is Ksh12,136.06.",
                    "read": 1
                },
                {
                    "address": "MPESA",
                    "direction": "inbound",
                    "timestamp": 1473413040000,
                    "rawBody": "KI94NZ5MGI confirmed.You bought Ksh10.00 of airtime on 9/9/16 at 12:24 PM.New M-PESA balance is Ksh152.00.",
                    "read": 1
                },
                {
                    "address": "+254729194910",
                    "direction": "outbound",
                    "timestamp": 1574620767564,
                    "rawBody": "please call me",
                    "read": 1
                },
                {
                    "address": "+254733456091",
                    "direction": "inbound",
                    "timestamp": 1579891167564,
                    "rawBody": "Check email",
                    "read": 1
                },
                {
                    "address": "+254722034142",
                    "direction": "inbound",
                    "timestamp": 1580495967564,
                    "rawBody": "Thanks!",
                    "read": 1
                }
            ]
        }
    ]
}

Create and Retrieve Assessment

When a borrower requests for a loan on your app, you will create a credit assessment for them using the apps.assessments.create API method.In this example, we will use the default credit assessment type for individual accounts, i.e assessmentTypes/personal_credit_standard.

In most cases, an assessment type is restricted to only certain subset of lending apps and/or lending accounts. See the assessmentTypes API reference for more information. The assessmentTypes.list API method also has a listing of all available types of lending assessments.

Create Assessment

POST https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/assessments

Path Parameters

NameTypeDescription

projectId

string

Project ID

appId

string

Application ID

Headers

NameTypeDescription

Content-Type

string

application/json

{
  "name": "projects/test-project/apps/test-app/assessments/76e49eb3-24a6-5e90-8d0f-40bfc88cd4a3",
  "uid": "27e9f80e-6402-5706-b3f6-fdfa60bf23fe",
  "status": 1,
  "createdAt": "2020-04-11T17:06:07.788Z",
  "assessmentId": "76e49eb3-24a6-5e90-8d0f-40bfc88cd4a3",
  "accountId": "borrower:10023",
  "assessmentType": "credit",
  "timestamp": "2020-04-11T09:00:00.000Z",
  "appVersionId": "v1",
  "result": null
}
{
	"accountId": "borrower:10023",
  "assessmentType": "assessmentTypes/personal_credit_standard",
  "timestamp": "2020-04-11T12:00:00+03:00"
}

The API is asynchronous and as such you will need to store the assessmentId returned in the response and then poll for the result by fetching this resource using the apps.assessments.get API method described below. In ordinary circumstances, the assessment will be processed within 90 seconds.

Get Assessment

GET https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/assessments/:assessmentId

Path Parameters

NameTypeDescription

assessmentId

string

Assessment ID received when creating an assessment.

appId

string

Application ID

projectId

string

Project ID

{
  "name": "projects/test-project/apps/test-app/assessments/Ym9ycm93ZXI6MTAwMjM7Y3JlZGl0OzE1MTc0NzU2MDAwMDA=",
  "uid": "b35161f5-d2fa-50ae-aa22-104df33abfbd",
  "status": 1,
  "createdAt": "2020-03-09T09:46:20.809Z",
  "assessmentId": "Ym9ycm93ZXI6MTAwMjM7Y3JlZGl0OzE1MTc0NzU2MDAwMDA=",
  "accountId": "borrower:10023",
  "assessmentType": "assessmentTypes/personal_credit_standard",
  "timestamp": "2018-02-01T09:00:00.000Z",
  "appVersionId": "v1",
  "result": {
    "type": "authorized",
    "reason": null,
    "message": null,
    "riskLevel": "normal",
    "riskScore": 0,
    "creditScore": 660,
    "creditRating": "good"
  }
}

Weza.io will return a result that will advise you on the credit and risk level for the borrower. If you decide to give out a loan based on this assessment, make sure to store the assessmentId returned in this response on your back end data store alongside your actual loan record and send that information when updating the borrower account so that we can determine whether the assessment was helpful to you. See the LoanSummary type reference for information on that.

PreviousGetting started with Lending Apps and Lending PolicyNextLoan Management

Last updated