Metropol CRB API v3.7

Document Name: MA Kenya API Developer Guide
Document Version: Version 3.7
MCRB API - Developer Guide

Version 3.7
Metropol Corporation
KCB Towers Upperhill,
P. O. Box 35331, 00200
Nairobi, Kenya
www.metropol.co.ke
Page | 1
Table of Contents
1. Overview ............................................................................................................................................... 4
2. Access & Protocol ................................................................................................................................. 4
3. Testing Tools ......................................................................................................................................... 4
4. API ......................................................................................................................................................... 5
4.1. API Service Endpoints ................................................................................................................. 5
4.2. API Headers ................................................................................................................................. 6
4.3. API Calls ....................................................................................................................................... 7
4.3.1. Report Type 1: [Identity Verification] ................................................................................... 8
4.3.2. Report Type 2: [Delinquency Status] ................................................................................... 10
4.3.3. Report Type 3: [Metro/Mobile Score] ................................................................................. 11
4.3.4. Report Type 4: [PDF Report] ................................................................................................ 13
4.3.5. Report Type 5: [JSON Report] .............................................................................................. 14
4.3.6. Report Type 6: [Identity Scrub] ........................................................................................... 18
4.3.7. Report Type 8: [Credit Info] ................................................................................................. 20
4.3.8. Report type 10: [Enhanced Credit Info] .............................................................................. 23
4.3.9. Report Type 11: [Enhanced Credit Info Mobile] ................................................................. 26
4.3.10. Report Type 12: [Full Enhanced Credit Info] ...................................................................... 30
4.3.11. Report Type 13: [Minified Credit Info] ................................................................................ 36
4.3.12. Report Type 14: [Full JSON Report] ..................................................................................... 37
4.3.13. Report Type 16: [Credit Accounts Summary Report] ........................................................ 41
4.3.14. Report Type 22: [Credit Accounts Summary Report] ........................................................ 43
4.3.15. API Health Check ................................................................................................................... 48
5. API Codes ............................................................................................................................................ 49
5.1. Report Types.............................................................................................................................. 49
5.2. Report Reasons .......................................................................................................................... 50
5.3. MCRB Identity Types................................................................................................................. 50
5.4. Delinquency Codes .................................................................................................................... 50
5.5. MCRB Lender Sector Codes ...................................................................................................... 51
5.6. Account Product Types ............................................................................................................. 51
5.7. Account Status Codes ................................................................................................................ 52
5.8. API Response Codes .................................................................................................................. 52
6. Document Version .............................................................................................................................. 54
Page | 2
Information contained in this specification is proprietary to Metropol Corporation. It shall not
be reproduced or disclosed in whole or in part to any party (other than to any individual who
has a need to peruse the content of this specification in connection with the purpose for
which it is submitted) or used for any purpose other than the purpose for which it is
submitted, without the written approval of Metropol Corporation Limited.
@2022 Metropol Corporation Limited
Page | 3
1. Overview
Welcome to the Metropol Credit Reference Bureau API documentation. In here you will find all
the information necessary to configure your system to make automated calls to the bureau.
Happy reading.
PS: in case of any hair pulling experiences please find us on Skype or drop us an email.
2. Access & Protocol

The API is only accessed via HTTPS on the hostname api.metropol.co.ke. DNS should be
configured to resolve the hostname if one is connecting via a custom connection e.g. Point to
Point or VPN.
All queries are performed by executing an HTTP POST, GET or PUT depending on the type of query
to the given hostname. Unless specified, for all report types the query body must be in JavaScript
Object Notation (JSON). In addition, also all responses from the API are in JSON.
The MCRB API uses the HTTP protocol to process calls. The API server responds to all queries with
JSON objects unless specified otherwise.
3. Testing Tools
To test API calls, you can use your preferred development language but for most languages, this
takes a tad longer when your only aim is to test the calls and responses. For this we recommend
using the following tools:
 curl – A UNIX CLI utility

 postman – a Google Chromes extension
 HTTPie – A python curl replacement (check GitHub for documentation)
Client Posts Query
$ curl -x POST <OPTIONS> https://api.metropol.co.ke:<portnumber>/<api-version-number>/<end-

point>
Page | 4
Metropol analytics server returns data in json format
{
“parameter 1”: “value 1”,
“parameter 2”: ” value 2”
}
4. API
4.1. API Service Endpoints
A valid call to the API has the URL root, port, version number and endpoint. When starting development,
always contact Metropol CRB to get the latest Version number of the URL.
Root URL: https://api.metropol.co.ke
Full URL: https://api.metropol.co.ke:<port-number>/<end-point>
1. Verify an Identity Number/Document:

endpoint: /identity/verify
2. Fetch all noncredit information available in the bureau for a given ID
endpoint: /identity/scrub
3. Fetch all delinquency status for an ID. Current & Past
endpoint: /delinquency/status
4. Fetch a consumer credit score for an ID
endpoint: /score/consumer
5. Fetch an Identity’s credit report in PDF
endpoint: /report/pdf
6. Fetch an identity’s credit report in JSON
endpoint: /report/json
7. Fetch a credit information for an ID
endpoint: /report/credit_info
8. Fetch enhanced credit information for an ID
endpoint: /report/credit_info_enhanced
NOTE: API testbed is available with all the above endpoints. Contact Metropol IT to get which version.
Page | 5
4.2. API Headers
Each API call must include 4 headers:

1. "Content-Type":"application/json"
2. “X-METROPOL-REST-API-KEY”: “DKKEIE3CKGPAIRJVN495JFJAJ”
3. “X-METROPOL-REST-API-
HASH”:“6b4412c63b19cd86e9939c43d115x961ef4357698da42f984287e6d0029c5671”
4. “X-METROPOL-REST-API-TIMESTAMP”: “20140708175839987843”
Content-Type
 For now, the API only returns data in JSON
X-METROPOL-REST-API-KEY
 Metropol will assign you this key. It is your Public API key
X-METROPOL-REST-API-HASH
 This is a SHA-256 blob that you generate using the Private Key that MCRB assigns to you.
 To generate the hash, concatenate a UTF-8 string of private_key + json_object + public_key +
timestamp and run your hashing function. The hash should be returned as hexadecimal digits.
X-METROPOL-REST-API-TIMESTAMP
 The current UTC (Coordinated Universal Time) sent as an integer minimum 20 characters.
 Format: Year, Month, Day, Hour, Minute, Second, Milliseconds
 This means that your server/computer has got the have some form of universal time sync as
there is a limit of the time difference a client and the API server can have. Currently its 45
seconds.
Page | 6
4.3. API Calls
Note 1:
For all API requests done on the Test Environment, the following Dummy ID’s are to be used:
 550000055
 660000066
 770000077
 880000088
 990000099
Note 2:
There are no spaces in the JSON object between the KEY:VALUE pair and also no spaces
between the different dictionary items e.g.
{“report_type”:1,“identity_number”:“880000088”,“report_type”:“001”}
Page | 7
4.3.1. Report Type 1: [Identity Verification]
Description: This report is used to verify an Identity Number of a given ID Type
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/identity/verify
Sample Request Header
curl –X POST \
-H “X-METROPOL-REST-API-KEY:XXXXXXXXXXXXXXXXXXX” \
-H “X-METROPOL-REST-API-HASH:6b4412….9c5671” \
-H “X-METROPOL-REST-API-TIMESTAMP:20140708175839987843” \
-H “Content-Type:application/json” \
-d ‘{“report_type”:1,\
“identity_number”:“880000088”,\
“identity_type”:“001”}’ \
JSON Object Request Parameters
Parameter Type Optional Description

report_type integer No The requested report type number
identity_number string No Identity Number to be verified
identity_type string No Type of Identity. Refer to Appendix: Identity Type
Sample JSON Response
{
"api_code":null,
"api_code_description":null,
"citizenship":"Kenyan",
"clan":null,
"date_of_birth":"1978-01-05",
"date_of_death":null,
"date_of_issue":null,
"dob":"1978-01-05",
"error":null,
"error_message":null,
"ethnic_group":null,
"family":null,
"fingerprint":null,
Page | 8
"first_name":"John",
"gender":"M",
"has_error":false,
"id_number":"880000088",
"identity_number":"880000088",
"identity_type":"001",
"identity_type_id":2,
"ipaddress":"192.168.20.42",
"last_name":"Doe",
"occupation":null,
"other_name":"Junior",
"photo":null,
"pin":null,
"place_of_birth":null,
"place_of_death":null,
"place_of_live":null,
"regoffice":null,
"serial_number":"123456789",
"signature":null,
"success":true,
"surname":"DOE",
"trx_id":"9d540825-8ca8-417d-ac7e-60648070abc6"
}
Page | 9
4.3.2. Report Type 2: [Delinquency Status]
Description:
This report is used to check if an Identity has a current or historical NPA.
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/delinquency/status
curl –X POST \
“identity_type”:“001”,\
“loan_amount”:10000}’ \

loan_amount integer No The amount of loan application amount
{
"api_code":null,
"delinquency_code":"005",
"delinquency_summary":"Historical delinquency True",
"has_error":false,
"loan_amount":2000,
"trx_id":"e9e0991e-d35c-4884-a793-dadf2a52cf41"
}
Page | 10
4.3.3. Report Type 3: [Metro/Mobile Score]
Description: This report is used to fetch Metro Score (Credit Score) or Mobile score for the
specified identity in the request. To fetch Metro score, mobile_score parameter should be set
to false or alternatively omitted. To fetch Mobile score mobile_score parameter should be set
to true.
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/score/consumer
curl –X POST \
-d ‘{“report_type”:3,“identity_number”:“880000088”, “identity_type”:“001” ,
“mobile_score”:false}’ \

If set to true, Mobile score is returned. If set to
mobile_score boolean Yes false or if it is not provided, API will return Metro
Score
{
"has_error":false,
"api_code":null,
"credit_score":"567",
"category":null,
Page | 11
"as_at": "2019-10-08",
}
Page | 12
4.3.4. Report Type 4: [PDF Report]
Description: This report is used to fetch the full Credit report in a binary PDF format.
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/pdf
curl –X POST \
“loan_amount”:2000, \
“report_reason”:1}’ \

Report_reason integer No The reason for the Credit Report generation
{
"has_error":false,
"api_code":null,
"trx_id":"6579d9a5-368f-4c8a-9125-db5a7d24f0b6",
"identity_number":12345678,
"reference_number":"3484BDKG394942",
"encoding":"base64",
"report":"Binary encoded data",
Page | 13
"report_reason":1
}
4.3.5. Report Type 5: [JSON Report]
Description: This report is used to fetch the Credit report in a JSON format.
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/json
curl –X POST \

Report_reason integer No The reason for the Credit Report generation
{
"account_info":[
{
"account_number":"DM_8820191767488",
"account_status":"Write-Off",
"current_balance":"5903.77000",
Page | 14
"date_opened":"2008-01-14",
"days_in_arrears":360,
"highest_days_in_arrears":360,
"is_your_account":false,
"last_payment_amount":"43.70000",
"last_payment_date":"2010-08-16",
"loaded_at":"2013-12-31 23:59:59",
"original_amount":"5762.07000",
"overdue_balance":"5903.77000",
"overdue_date":"2010-10-09",
"product_type_id":2
},
{
"account_status":"Closed",
"date_opened":"2014-04-29",
"loaded_at":"2010-11-30 23:59:59",
"overdue_date":null,
"product_type_id":8
},
{
"account_number":"DM_880424000250088\ufffd",
Page | 15
"date_opened":"2014-04-22",
"loaded_at":"2010-10-31 23:59:59",
"product_type_id":14
}
],
"api_code":null,
"credit_score":303.80000000000007,
"has_error":false,
"has_fraud":false,
"is_gurantor":true,
"lender_sector":{
"sector_bank":{
"account_npa":1,
"account_performing":1,
"account_performing_npa_history":0
},
"sector_other":{
"account_npa":0,
Page | 16
}
},
"no_of_bounced_cheques":{
"last_12_months":2,
"last_3_months":0,
"last_6_months":0
},
"no_of_credit_applications":{
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"no_of_enquiries":{
"last_12_months":401,
"last_3_months":58,
"last_6_months":284
},
"ppi_analysis":{
"month":"2019-09-04",
"ppi":191.0,
"ppi_rank":"M9"
},
"reported_name":[
"John The Walker",
"Walker John"
],
"verified_name":{
"first_name":"Peter",
"other_name":null,
"surname":null
}
}
Page | 17
4.3.6. Report Type 6: [Identity Scrub]
Description: This report is used to fetches non account information available for a given Identity
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/identity/scrub
curl –X POST \
“identity_type”:“001”}’ \

{
"has_error":false,
"api_code":null,
"trx_id":"9579d9a5-368f-4c8a-9125-db5a7d24f0b9",
"names":[
"John Doe"
],
"date_of_being":[
"1956-08-19"
],
Page | 18
"gender":[
"M"
],
"phone":[
"0722222222"
],
"email":[
"john.doe@gmail.com"
],
"postal_address":[
{
"town":"Nakuru",
"number":"2222",
"code":"00200",
"country":"KENYA"
}
],
"physical_address":[
{
"town":"Railways Estate, House 54",
"address":"Nakuru",
"country":"KENYA"
}
],
"employment":[
{
"employment_date":null,
"employer_name":"Testing Metropol"
}
]
}
Page | 19
4.3.7. Report Type 8: [Credit Info]
Description: This report is used to fetch the Credit Information for a given identity number
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/credit_info
curl –X POST \
“identity_number”:“880000088”, \

Report_reason integer No The reason for the Credit Report Generation
{
"account_info":[
{
"account_status":"Fully Settled",
"date_opened":"2008-01-14",
Page | 20
"loaded_at":"2014-08-31 23:59:59",
"overdue_date":"None",
"product_type_id":7
},
{
"account_status":"Active",
"date_opened":"2014-04-29",
"loaded_at":"2014-08-31 23:59:59",
"product_type_id":8
},
{
"date_opened":"2014-04-22",
"loaded_at":"2014-08-31 23:59:59",
}
],
Page | 21
"api_code":null,
"credit_score":501,
"has_error":false,
"has_fraud":false,
"is_guarantor":false,
"lender_sector":{
"sector_bank":{
"account_npa":0,
},
"sector_other":{
"account_npa":0,
}
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"no_of_enquiries":{
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"trx_id":"ce55d92f-7316-487a-8605-3d21c00cbe83"
}
Page | 22
4.3.8. Report type 10: [Enhanced Credit Info]
Description: This report is used to fetch the Credit Information for a given identity including
guarantors and stakeholder details
Note:
 Guarantors: entities that have guaranteed the subject
 Stakeholders: entities that have stakes in the subject entity
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/credit_info_

enhanced
curl –X POST \
“application_ref_no”:“ 45555”, \

Application_ref_no string Yes Credit Application Reference number (Optional)
Page | 23
{
"account_info":[
{
"account_number":"BBBBBBBBBB",
"account_status":"C",
"date_opened":"2011-05-25",
"loaded_at":"2012-07-01 00:00:08",
"overdue_date":"2011-07-25",
"product_type_id":3
},
{
"account_number":"AAAAAAAAAAA",
"account_status":"K",
"date_opened":"2008-09-04",
"loaded_at":"2014-09-30 23:59:59",
"product_type_id":7
}
],
"api_code":null,
"application_ref_no":"45555",
"credit_score":28,
"guarantors":[
{
"account_number":"QQQQQQQQ",
"identity_number":"1234"
Page | 24
},
{
"account_number":"DDDDDDDDD",
"identity_number":"333"
}
],
"has_error":false,
"has_fraud":false,
"lender_sector":{
"sector_bank":{
"account_npa":1,
}
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"no_of_enquiries":{
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"stakeholders":[
{
"identity_number":"DLLL",
"stakeholder_type":"C"
},
{
"identity_number":"WEDF",
"stakeholder_type":"C"
},
{
Page | 25
"stakeholder_type":"B"
}
],
"trx_id":"51c682cf-4cf9-498f-8cc1-1f78e6c66ed6"
}
4.3.9. Report Type 11: [Enhanced Credit Info Mobile]
Description: This report is used to fetch the Credit Information for a given identity with income
estimation.
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/creditinfo/mobile
curl –X POST \

Page | 26
{
"account_info":[
{
"account_currency":"KES",
"account_number":"QA123123",
"date_opened":"2015-10-15",
"last_payment_amount":"None",
"loaded_at":"2016-04-11 09:51:39",
},
{
"account_number":"XZ123123",
"date_opened":"2015-10-22",
"last_payment_amount":"None",
"loaded_at":"2016-04-11 09:51:39",
},
{
"account_number":"CD454545",
"date_opened":"2016-03-31",
Page | 27
"last_payment_date":"None",
"loaded_at":"2016-05-31 23:59:59",
},
{
"account_number":"AC231231",
"date_opened":"2016-05-26",
"last_payment_date":"None",
"loaded_at":"2016-06-30 23:59:59",
}
],
"api_code":null,
"credit_score":779,
"has_error":false,
"has_fraud":false,
"income_estimation":{
"estimated_amount":"1118.00"
},
"lender_sector":{
"sector_bank":{
"account_npa":0,
Page | 28
"account_performing_hist":2,
},
"sector_other":{
"account_npa":0,
"account_performing_hist":0,
}
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"no_of_enquiries":{
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"phone_number": [
"254710123456"
],
"trx_id":"34cf2f18-bfa9-4d94-be3f-a091a2f186a4"
}
Page | 29
4.3.10. Report Type 12: [Full Enhanced Credit Info]
Description: This report is used to fetch the Credit Information, Identity Verification, Identity
Scrub, last 12 Months Metro Score and last 12 months Payment Performance Index (PPI) for a
given identity.
HTTP Method: POST
curl –X POST \


{
"account_info":[
{
"date_opened":"2014-04-22",
Page | 30
"loaded_at":"2014-08-31 23:59:59",
}
],
"api_code":null,
"credit_score":467.59999999999997,
"guarantors":[
],
"has_error":false,
"has_fraud":false,
"identity_scrub":{
"api_code":null,
"date_of_being":[
"1956-08-19"
],
"email":[
"johnthe.walker@gmmail.com"
],
"employment":[
{
"employer_name":"Testing Metropol",
"employment_date":null
}
],
"gender":[
"M"
],
"has_error":false,
"names":[
"Walker John",
"John The Walker"
],
"phone":[
"0722222222"
],
Page | 31
{
"address":"Nakuru",
"country":"Kenya",
"town":"Nakuru"
}
],
"postal_address":[
{
"code":"00200",
"country":"Kenya",
"number":"2222",
"town":"Nakuru"
}
]
},
"identity_verification":{
"api_code":null,
"clan":null,
"date_of_birth":"1973-05-05",
"dob":"1973-05-05",
"error":null,
"family":null,
"fingerprint":null,
"gender":"M",
"has_error":false,
"id_number":"880000088",
"ipaddress":"127.0.0.1",
"last_name":"Marangi",
"occupation":null,
"other_name":"Marangi",
"photo":null,
"pin":null,
"regoffice":null,
"signature":null,
Page | 32
"success":true,
"surname":"Marangi",
"trx_id":"61d1aaba-c5fe-43cc-9cce-b3430fbeb715"
},
"metro_score_trend":[
{
"credit_score":400,
"month":"2018-7-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-4-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-9-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-10-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-8-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":500,
"month":"2018-3-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-1-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
Page | 33
"month":"2018-5-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2017-11-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-6-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2018-2-05",
"ppi":0.0,
"ppi_rank":M1
},
{
"credit_score":499,
"month":"2017-12-05",
"ppi":0.0,
"ppi_rank":M1
}
],
"lender_sector":{
"sector_bank":{
"account_npa":0,
},
"sector_other":{
"account_npa":0,
}
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"last_12_months":0,
"last_3_months":0,
Page | 34
"last_6_months":0
},
"no_of_enquiries":{
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"stakeholders":[
],
"trx_id":"30b25c91-cd30-43ed-a05f-ba470da61796"
}
Page | 35
4.3.11. Report Type 13: [Minified Credit Info]
Description: This report is fetches a summary of credit information for a given identity number.
HTTP Method: POST
curl –X POST \


{
"has_error":false,
"negative_his_indicator":0,
"npl_flag":1,
"outstanding_balance":719742.2,
Page | 36
"trx_id":"7e6fdab2-1450-4edd-9676-6c5e84e86d6a"
}
4.3.12. Report Type 14: [Full JSON Report]
Description: This report is used to fetch the Full Credit report in a JSON format. It includes,
Identity Verification, Identity Scrub, Credit Info, Stakeholder Info and Guarantor Info
HTTP Method: POST
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/json
curl –X POST \


{
"account_info":[
{
Page | 37
"date_opened":"2014-04-22",
"loaded_at":"2014-08-31 23:59:59",
}
],
"api_code":null,
"credit_score":467.59999999999997,
"guarantors":[
],
"has_error":false,
"has_fraud":false,
"identity_scrub":{
"api_code":null,
"date_of_being":[
"1956-08-19"
],
"email":[
"johnthe.walker@gmmail.com"
],
"employment":[
{
"employer_name":"Testing Metropol",
"employment_date":null
}
],
"gender":[
"M"
],
"has_error":false,
Page | 38
"names":[
"Walker John",
"John The Walker"
],
"phone":[
"0722222222"
],
{
"address":"Nakuru",
"country":"Kenya",
"town":"Nakuru"
}
],
"postal_address":[
{
"code":"00200",
"country":"Kenya",
"number":"2222",
"town":"Nakuru"
}
]
},
"identity_verification":{
"api_code":null,
"clan":null,
"date_of_birth":"1973-05-05",
"dob":"1973-05-05",
"error":null,
"family":null,
"fingerprint":null,
"gender":"M",
"has_error":false,
"id_number":"880000088",
Page | 39
"ipaddress":"127.0.0.1",
"last_name":"Marangi",
"occupation":null,
"other_name":"Marangi",
"photo":null,
"pin":null,
"regoffice":null,
"signature":null,
"success":true,
"surname":"Marangi",
"trx_id":"61d1aaba-c5fe-43cc-9cce-b3430fbeb715"
},
"lender_sector":{
"sector_bank":{
"account_npa":0,
},
"sector_other":{
"account_npa":0,
}
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"no_of_enquiries":{
"last_12_months":0,
"last_3_months":0,
"last_6_months":0
},
"stakeholders":[ ],
Page | 40
"trx_id":"30b25c91-cd30-43ed-a05f-ba470da61796"
}
4.3.13. Report Type 16: [Credit Accounts Summary Report]
Description: This report gives a summary of credit information in terms of total number of:
 mobile loan accounts,
 generic loan accounts (Non-mobile accounts),
 monthly installments for active generic loans
 accounts in arrears
 accounts in NPL,.
HTTP Method: POST
curl –X POST \

Page | 41
{
"api_code": null,
"api_code_description": null,
"credit_info": {
"average_principal_mobile_loans_active": 100.0,
"average_principal_mobile_loans_closed": 0.0,
"generic_account_count": 0,
"generic_account_count_closed": 0,
"generic_account_in_arrears_count": 0,
"generic_account_npa_count": 0,
"mobile_account_count_active": 1,
"mobile_account_count_closed": 0,
"mobile_account_in_arrears_count": 0,
"mobile_account_npa_count": 1,
"total_monthly_instalment_generic": 0.0
},
"has_error": false,
"identity_number": "880000088",
"identity_type": "001",
"phone_number": [
"254712345678"
],
"reported_name": [
"PETER MARANGI",
"MARANGI PETER"
],
"verified_name": {
"first_name": null,
"other_name": null,
"surname": null
}
}
Page | 42
4.3.14. Report Type 22: [Credit Accounts Summary Report]
Description: This report gives a summary of a customer’s credit accounts. It also gives 12
months history on below:
 Account status
 Metro Score
 Current Balance
 Days in arrears
 Last Payment date
The report also gives summary for total outstanding and total overdue amounts for non
performing accounts, historical non-performing accounts and performing accounts.
HTTP Method: POST
curl –X POST \

Page | 43
{
"account_info": [
{
"account_number": "223456789",
"account_status_name": "Active",
"currency_code": "KES",
"current_balance": 7156217.65,
"date_opened": "2017-07-19",
"days_in_arrears": 0,
"delinquency_code": "003",
"highest_days_in_arrears": 0,
"loaded_at": "2021-01-01",
"original_amount": "8380000.00000",
"overdue_balance": 0.0,
"overdue_date": null,
"product_type_name": "Mortgage",
"account_history": [{
"account_status": "Active",
"last_payment_amount": "33625.50000",
"last_payment_date": "2020-12-24",
"month": "2021-01-01",
"overdue_balance": "0.00000"
},
{
"month": "2020-12-01",
},
{
"month": "2020-11-01",
},
Page | 44
{
"month": "2020-10-01",
},
{
"month": "2020-09-01",
}
]
},
{
"account_number": "355516815",
"account_status_name": "Active",
"currency_code": "KES",
"current_balance": 22054.15,
"date_opened": "2018-02-26",
"loaded_at": "2021-01-01",
"original_amount": "475005.00000",
"overdue_balance": 0.0,
"overdue_date": null,
"product_type_name": "Personal Loan",
"account_history": [{
"month": "2021-01-01",
},
{
Page | 45
"month": "2020-12-01",
},
{
"month": "2020-11-01",
},
{
"month": "2020-10-01",
},
{
"month": "2020-09-01",
}
]
}
],
"api_code": null,
"api_code_description": null,
"customer_name": "PETER MARANGI",
"has_error": false,
"identity_number": "880000088",
Page | 46
"identity_type": "001",
"lowest_days_in_arrears": 0,
"max_credit_score": 727,
"min_credit_score": 727,
"monthly_score": [{
"credit_score": 727,
"month": "2021-05-06"
},
{
"month": "2021-06-06"
},
{
"month": "2021-07-06"
},
{
"month": "2021-08-06"
},
{
"month": "2021-09-06"
},
{
"month": "2021-10-06"
},
{
"month": "2021-11-06"
},
{
"month": "2021-12-06"
},
{
"month": "2022-01-06"
},
{
Page | 47
"month": "2022-02-06"
},
{
"month": "2022-03-06"
},
{
"month": "2022-04-06"
}
],
"total_outstanding_amount": 7205332.600000001,
"total_outstanding_npa": 0.0,
"total_outstanding_npa_history": 0.0,
"total_outstanding_performing": 7205332.600000001,
"total_overdue_amount": 0.0,
"total_overdue_npa": 0.0,
"total_overdue_npa_history": 0.0,
"total_overdue_performing": 0.0,
"trx_id": "TEST-REF-123"
}
4.3.15. API Health Check
Description: This endpoint is for checking availability of MCRB API service. The endpoint does
not require any parameter.
HTTP Method: GET
Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/health
Response Returned:
The API will return a JSON as shown below:
{
"api_code": "E200",
"api_code_description": "API SERVICES AVAILABLE",
"has_error": false
}
Page | 48
5. API Codes
The MCRB API returns standard HTTP status codes with each call. In all API processed queries,
each result returns at least the following fields:
 has_error
 api_code
 api_code_description
Additional Information:
 When there is an error, the “has_error = True” with an appropriate “api_code” and
“api_code_description” will be returned with a relevant HTTP status code e.g. 400, 402,
500 etc.
 When there is no error, the result will be “has_error=False” and the “api_code” and
“api_code_description” will be null.
5.1. Report Types
MCRB API: Report Type

Report Type Description Detailed Description
1 Identity Verification Verify an Identity Number of a given ID Type
2 Delinquency Report Check if an Identity has a current or historical NPA
3 Check Credit Score Fetch Credit score of a given Identity
4 PDF Credit Report Fetch full credit report for a given Identity
5 JSON Credit Report Fetch full credit report for a given Identity.
6 Identity Scrub Get non account information available for a given Identity
8 Credit Info Get all Credit Information for a given identity
Enhanced Credit Info Get all Credit Information for a given identity with
10
guarantors and stakeholder details
Credit Info with Get all Credit Information for a given identity plus income
11
Income Estimation estimation
Full Enhanced Credit Get all Credit Information, Identity Verification, Identity
12 Info Scrub, last 12 Months Metro Score and last 12 months
Payment Performance Index (PPI) for a given identity.
Minified Credit Info Get a minified summary of credit information for a given
13
identity number.
Full JSON Credit Full Credit report in a JSON format. It includes, Identity
14 Report Verification, Identity Scrub, Credit Info, Stakeholder Info
and Guarantor Info
Credit info Summary Credit information summary on mobile accounts and
16 generic loans
Credit Info Summary Credit information summary – 12 month historical

22
performance on Metro score, account status, days in
Page | 49
arrears, current balance. Provides summary of
outstanding and overdue balances for NPA, historical NPA
and performing accounts
5.2. Report Reasons
MCRB API: Report Reason

Code Description
1 New credit application
2 Review of existing credit
3 Verify customer details
4 Direct customer request
5.3. MCRB Identity Types
MCRB API: Identity Type

Code Description
001 National ID
002 Passport
003 Service ID
004 Alien Registration
005 Company/Business Registration
5.4. Delinquency Codes
MCRB API: Delinquency Codes

Delinquency
Code Report Name Report Description
001 Identity not found ID number not found in the database
ID number has been found but it has no credit
002 No account information information
003 No delinquency ID Number has credit info with No NPA
Currently delinquent ID Number has credit information with at least one
004 True current NPA
Historical delinquency ID Number has credit information with at least one
005 True Historical NPA
Page | 50
5.5. MCRB Lender Sector Codes
MCRB API: Lender Sector

Code Description
sector_bank Banking Industry
sector_mfb Micro Finance Banks
sector_mfi Micro Finance Institutions
sector_sacco Sacco Organizations
sector_other Other Industries (Sectors)
5.6. Account Product Types
MCRB API: Account Product Type

Code Description
1 Unknown
2 Current Account
3 Loan Account
4 Credit Card
5 Line of Credit
6 Revolving Credit
7 Overdraft
8 Credit Card
9 Business Working Capital
10 Business Expansion Loan
11 Mortgage
12 Asset Finance Loan
13 Trade Finance Facility
14 Personal Loan
18 Mobile Banking Loan
19 Other
Note: Product Codes 15, 16, 17 are missing by design
Page | 51
5.7. Account Status Codes
MCRB API: Account Status Type

Code Description
- Unknown
A Closed
B Dormant
C Performing
D Non-Performing
E Write-Off
F Legal
G Collection
H Active
I Terms Extended
J Early Settlement
K Fully Settled
L Revoked
M Suspended
P Paid Up
Q Disability, Deceased,
Insurance Claim
R Deferred
N Not Updated
5.8. API Response Codes
MCRB API: Response Codes

Response
Code Error Description Error Detail
Please contact MCRB API
E001 Administrator Internal error occurred
E002 Empty API Key API call doesn’t include the API key
E003 Not Authorized API key is not authorized to access a service
Public key has expired or has been flagged as
E004 Invalid public key invalid
E005 Invalid Content Type API call has invalid content type
E006 Invalid JSON object API call has invalid JSON object
E007 Missing parameter: report_type report_type key hasn't been passed
Missing parameter:
E008 identity_number identity_number key hasn't been passed
E009 Missing parameter: identity_type identity_type key hasn't been passed
Page | 52
E010 Empty report_type report_type value hasn't been passed
E011 Invalid report type Invalid report_type value has been passed
E012 Empty identity_number identity_number value hasn't been passed
E013 Empty identity_type identity_type value hasn't been passed
E014 Invalid identity_type Invalid identity_type value has been passed
Invalid query for selected Invalid combination of parameters for a type of
E015 report_type report
E016 Service not yet available Service not available for public use
E017 Identity not found ID Number could not be found in the database
ID Number passed not among test
E018 set During testing, there are specific IDs to be used
E019 Restricted identity_type Queried an indentity type that isn't accessible yet
E020 Missing parameter: loan_amount loan_amount key hasn't been passed
E021 Empty loan_amount loan_amount value hasn't been passed
E022 Invalid loan_amount Invalid loan_amount value has been passed
E023 Empty Time Stamp API call header doesn't include a Time Stamp
E024 Invalid Time Stamp API call header has an invalid Time Stamp
Time delay between query generation and API
E025 Time Mismatch receiving the request
E026 Empty Hash API call header doesn't include a Hash
Hash sent in API call doesn't match with Hash
E027 Hash Mismatch generated by the server
API Account hasn’t been fully configured or
E028 Account setup incomplete activated. Contact MCRB
API account doesn’t have access to the report
E029 Unauthorized report specified in the query
E030 Invalid private key Private key has been invalidated. Contact MCRB
Missing Parameter: API call doesn't include a Reason for accessing the
E031 report_reason report
E032 Invalid report_reason Invalid value for report reason passed
E033 Unknown report_reason code Report reason provided not among allowed codes
Similar request already received in the last 60
E409 Duplicate Request seconds
Page | 53
6. Document Version
Version Date Comment
1.0 March 2nd 2014 Initial API document
1.1 April 24th 2014 Added Identity Verification
1.2 June 16th 2014 Added API codes & changed test port
1.3 June 20th 2014 Corrected entries in report type
Added fields in report 5: no. of. Bounced cheques, enquiries &
1.4 June 24th 2014 formatted the no of credit applications different
Added delinquency code to JSON Report
Renamed “error_code” to “api_code” & “error_summary” to
“api_code_description”
1.5 June 26th 2014 Made the API Codes sequential
nd
1.6 July 2 2014 Added Report Type 6. Identity Scrub
Added Private Key & Hash Header,
th
2.0 July 6 2014 API Versioning & URL layout
Clarification of hash string Encoding & JSON object format,
Changing of some key values in JSON report from numeric to
2.1 July 22nd 2014 string e.g. 3, 6, 12 to last_3_months, last_6_months etc
Changed keys for lender sector section from numeric to string
2.2 July 30th 2014 i.e 1,2,3 etc to sector_bank, sector_mfb etc
Added ‘is_your_account’ in the account_info block in json
report
2.3 August 27th 2014 Sanitized the product_type codes
Corrected UTC timestamp call and introduced trx_id as a
2.4 March 11th 2015 response to all calls
Added report type 8 which is a credit information API which
will eventually replace the soon to be deprecated Full JSON
2.5 June 12th 2015 API.
th
2.6 May 20 2016 Added enhanced report type 10
th
2.7 July 20 2016 Added account status code field in enhanced report
Modified report type 10 to cater for application_ref_number
2.8 September 8th ,2016 request
Added account status and highest arrears days in report type
2.9 January 10, 2017 8
Added Dummy Test ID’s as well as loan_amount on Report
3.0 May 29, 2018 PDF
3.1 Nov 26, 2018 Added Report Types 12, 13 and 14
Added Payment Performance Index (PPI) to Report Type 5
3.2 January 18 2019 Added PPI rank to report type 12
Added Report Type 16
3.3 September 4, 2019 Added Reported Names and Verified names to Report Type 5
3.4 October 7 2019 Added phone_number to report type 11
Added restriction to prevent processing of a similar request
3.5 January 17 2020 received less than a minute from the first request.
Page | 54
Added Mobile Score to report type 3
3.6 November 27 2020 Added Health check endpoint.
3.7 April 18 2022 Added report type 22
Page | 55

Metropol CRB API v3.7

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Metropol CRB API v3.7

Uploaded by

Copyright:

Available Formats

Document Name: MA Kenya API Developer Guide

Document Version: Version 3.7

MCRB API - Developer Guide

KCB Towers Upperhill,

P. O. Box 35331, 00200

@2022 Metropol Corporation Limited

2. Access & Protocol

 curl – A UNIX CLI utility

Client Posts Query

$ curl -x POST <OPTIONS> https://api.metropol.co.ke:<portnumber>/<api-version-number>/<end-

Root URL: https://api.metropol.co.ke

Full URL: https://api.metropol.co.ke:<port-number>/<end-point>

1. Verify an Identity Number/Document:

Each API call must include 4 headers:

 For now, the API only returns data in JSON

Description: This report is used to verify an Identity Number of a given ID Type

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/identity/verify

Sample Request Header

JSON Object Request Parameters

Parameter Type Optional Description

Sample JSON Response

This report is used to check if an Identity has a current or historical NPA.

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/delinquency/status

Sample Request Header

JSON Object Request Parameters

Parameter Type Optional Description

Sample JSON Response

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/score/consumer

Sample Request Header

JSON Object Request Parameters

Parameter Type Optional Description

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/pdf

Sample Request Header

Parameter Type Optional Description

Sample JSON Response

4.3.5. Report Type 5: [JSON Report]

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/json

Sample Request Header

Parameter Type Optional Description

Sample JSON Response

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/identity/scrub

Sample Request Header

JSON Object Request Parameters

Parameter Type Optional Description

Sample JSON Response

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/credit_info

Sample Request Header

JSON Object Request Parameters

Parameter Type Optional Description

Sample JSON Response

HTTP Method: POST

Test URL: https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/report/credit_info_

Sample Request Header

JSON Object Request Parameters

Parameter Type Optional Description

4.3.9. Report Type 11: [Enhanced Credit Info Mobile]