Document Name: Metropol API Data Submission

Document Version: Version 1.2

Developer Guide- API Data Submission

Version 1.2
12th July 2019

Metropol Corporation

KCB Plaza Upperhill,

P. O. Box 35331, 00200

Nairobi, Kenya

www.metropol.co.ke
Notice

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.

@2019 Metropol Corporation Limited

Table of Contents

Notice ............................................................................................................................................................ 2
1. Overview ............................................................................................................................................... 4
2. Access & Protocol ................................................................................................................................. 4
3. Testing Tools ......................................................................................................................................... 4
4. API ......................................................................................................................................................... 5
4.1. API Service Endpoints ................................................................................................................... 5
4.2. API Calls ......................................................................................................................................... 6
4.2.1. Client Authentication ............................................................................................................ 7
4.2.2. Data Submission .................................................................................................................... 8
4.2.3. Get File Status ..................................................................................................................... 59
4.2.4. Fetching Error Logs ............................................................................................................. 65
4.2.5. Response Data to Call Back URL.......................................................................................... 70
5. API Reference Codes ........................................................................................................................... 71
5.1. Submission Types ........................................................................................................................ 71
5.2. Institution Refs ............................................................................................................................ 71
5.3. Response Codes .......................................................................................................................... 71
5.4. API Codes .................................................................................................................................... 72
5.5. Validation Status Codes .............................................................................................................. 72
5.6. Submission Files Data Refs .......................................................................................................... 73
5.6.1. Template v3 - Monthly Batch Data Refs ............................................................................. 73
5.6.2. Template v4 - Monthly Batch Data Refs ............................................................................. 73
5.6.3. Template v4 - Daily Batch Data Refs ................................................................................... 73
6. Document Version .............................................................................................................................. 74

Page | 3
1. Overview
Welcome to the Metropol Credit Reference Bureau Data Submissions API documentation. In here
you will find all the information necessary to configure your system to make automated calls for
data submission to the bureau.
The API follows the data submission guidelines specified in Data Submission Templates (DST)
version 3 and 4. It is important to read and understand the DST documents before using this API
to make data submissions.

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 requests 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. Forty

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>

Metropol analytics server returns data in json format

{“parameter 1”:“value 1”,“parameter 2”:”value 2”}

Page | 4
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>/<api-version>/<end-point>

Data Submission Endpoints

 JSON data submission:

endpoint: /datasubmission/submit/data
 File data submission.
endpoint: / datasubmission/submit/file

File Status Endpoints

 Fetch list of submitted files/JSON data

endpoint: /datasubmission/upload/requests
 Fetch status of a single file/JSON submitted for validation
endpoint: / datasubmission/upload/file

Error Logs Endpoints

 Endpoint to invoke generation of error logs.

endpoint: /datasubmission/error/generatelog
 Endpoint to fetch error log files
endpoint: /datasubmission/error/geterrorlist
 Endpoint to fetch error log for a single file
endpoint: /datasubmission/error/geterror

Page | 5
4.2. API Calls

The API allows Credit Information Providers (CIP) to first submit their authentication details
before they can submit their data. CIP is authorized, they will receive an access token which
they have to include in the subsequent request to submit data.
The CIP will make the Submission Request and include a callback URL for MCRB to call at end of
data processing. The submission of data can be done in two ways: data files or JSON. Both of
these have different end points.
The submitted JSON/file data is validated and a success or failure response is sent back to the
CIP. Once processing is complete, the Error logs and Error files will be generated and posted to
the CIP provided callback URL.

CIP Client MCRB

Authentication Request
Validation &
Access Token Authentication

File/JSON Submission Request

Request Submission Request
Validation
Submission success/failure response

Data Validation &

Processing
Notify Validation complete

Request generation of error logs

Acknowledge request

Request error list/error logs

Error list/error logs response

Request list of files/single file submitted

validation status

Page | 6
4.2.1. Client Authentication
This endpoint is used for authentication and getting OAuth access token. To get authorization
you will need a Basic Auth authorization token. The Basic Auth string is a base64 encoding of
the public and private keys provided by Metropol i.e. YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY

The API supports client_credentials grant type.

HTTP Method: POST

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/authenticate

Sample Request

curl -X POST \
'https://api.metropol.co.ke:1234/api/v1/datasubmission/authenticate?grant_type=client_credentials'
\
-H 'Authorization: Basic
UXJNbkU5YkZDaXVMdHVwUTVLUEVvUXlTYlBYamNLc1A6YjdBYUZhRXI2eUIza3ROUw==' \
-H 'cache-control: no-cache'

JSON Object Request Parameters

Parameter Type Optional Description

grant_type string No The grant type expected is: client_credentials

Sample JSON Response

{
"expires_in":3599,
"token_type":"bearer",
"access_token":"eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZGF0YS1zdWJtaXNzaW9uLWFwa
SJdLCJzY29wZSI6WyJyZWFkIiwid3JpdGUiXSwiZXhwIjoxNTQzNDEyNTA3LCJqdGkiOiJjMzY1OD
BkYi0wMGU3LTQxMTQtYTAxNC1iMWE4NTdiOGI3YzUiLCJjbGllbnRfaWQiOiJENG5uOHdkS05ZTWF
3RVNsTWhiS0padlZRV1NBYm1rcyJ9.qhfRrrj3Sl3ID0UFvjbCR5vCZeotVBkwpMdUYnE54Ow"
}

Page | 7
4.2.2. Data Submission
Using the API, an institution can submit data to MCRB either as a CSV file or in JSON format. The
API has different endpoints to handle the two types of format.

4.2.2.1. CSV File Data Submission

This endpoint enables an institution to submit CSV data files MCRB. You need to provide the
access token in the request.

HTTP Method: POST

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/submit/file

Sample Request

curl -X POST \
https://api.metropol.co.ke:1234/api/v1/datasubmission/submit/file \
-H 'Authorization: Bearer
eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZGF0YS1zdWJtaXNzaW9uLWFwaSJdLCJzY29wZSI6WyJyZWFkIiwid
3JpdGUiXSwiZXhwIjoxNTUxMzM3OTU2LCJhdXRob3JpdGllcyI6WyJST0xFXzE2Il0sImp0aSI6Ijc4OGI4ZDF
mLWM0YmEtNDVkYS1iMDQ5LWMzYjZiYzkwMDdhNSIsImNsaWVudF9pZCI6IlFyTW5FOWJGQ2l1THR1
cFE1S1BFb1F5U2JQWGpjS3NQIn0.8Fc1tX1N8KqS7_TnfxEGvV4_rCAQ65Gs0QnrKSGiBSM' \
-H 'Postman-Token: 3029c579-e9a0-4abe-9e8e-aed26fd64a47' \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F templateVersion=3 \
-F submissionType=M \
-F callbackUrl=string \
-F 'file=@D:\MTL\Documents\QA Testing\DVT\Load File\CRBBCE20180810001.B123' \
-F finalSubmissionState=true
Request Parameters

Parameter Type Optional Description

templateVersion string No Template version

submissionType string No Type of submission- Daily Update or Monthly batch

finalSubmissionState boolean No Test submission or a final submission

callbackUrl string No Client URL to update with validation status

file Array[file] No CSV data file to be submitted

Page | 8
Sample Success Response for CSV File Submission

{
"success":true,
"has_error":false,
"api_code":1010,
"api_code_description":"File Submitted Successful",
"trx_id":"FQHM-T9PE-20190227"
}

Sample JSON Fail Response for CSV File Submission

{
"success":false,
"has_error":true,
"api_code":1000,
"api_code_description":"No file Attached",
"trx_id":"00d3d952-3aa1-11e9-9c7d-d5e9df3f31d6"
}

Page | 9
4.2.2.2. JSON Data Submission
This endpoint is used for data submission in JSON format. You need to include the access token
in your request header. The expected content type is “application/json”. The data element can
receive one or more objects of the same file

HTTP Method: POST

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/submit/data

Sample Request

curl -X POST \
https://api.metropol.co.ke:1234/api/v1/datasubmission/submit/data \
-H 'Authorization: Bearer
eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZGF0YS1zdWJtaXNzaW9uLWFwaSJdLCJzY29wZSI6WyJyZWFkIiwid
3JpdGUiXSwiZXhwIjoxNTUxMzM3OTU2LCJhdXRob3JpdGllcyI6WyJST0xFXzE2Il0sImp0aSI6Ijc4OGI4ZDF
mLWM0YmEtNDVkYS1iMDQ5LWMzYjZiYzkwMDdhNSIsImNsaWVudF9pZCI6IlFyTW5FOWJGQ2l1THR1
cFE1S1BFb1F5U2JQWGpjS3NQIn0.8Fc1tX1N8KqS7_TnfxEGvV4_rCAQ65Gs0QnrKSGiBSM' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: dc018a3f-a751-4e0c-885a-326aa3f1ceae' \
-H 'cache-control: no-cache' \
-d '{
"template_version": "3",
"callback_url": "http://yourcallbackurl.com",
"institution_ref": "B",
"is_final_submission": true,
"submission_date": "20181002",
"submission_type": "M",
"data_ref": "CI",
"data": [
{
"registered_name": "JOHN DOE",
"trading_name": "JOHN DOE",
"reg_date": "19500101",
"reg_number": "852147654",
"prev_reg_no": "0",
"nationality": "KE",
"client_no": "121245625",
"account_no": "X1223456782",
"old_account_no": "",
"company_type": "K",
"industry_code": "012",

Page | 10
"annual_turnover": "0",
"pin_no": "0",
"vat_no": "0",
"number_of_shares": "1",
"trading_status": "002",
"trading_status_date": "20170119",
"main_phone": "0720123456",
"other_phone": "0721123456",
"postal_address1": "C/O XYZ",
"postal_address2": "C/O XYZ",
"town": "Nairobi",
"country": "KE",
"post_code": "00100",
"physical_address1": "NAIROBI",
"physical_address2": "PO BOX 13456",
"plot_no": "0",
"physical_location_town": "Nairobi",
"physical_location_country": "KE",
"lenders_reg_name": "XYZ BANK",
"lenders_trading_name": "XYZ BANK",
"lenders_branch_name": "NAIROBI BRANCH",
"lenders_branch_code": "B001",
"account_indicator": "J",
"account_holder_type": "A",
"account_product_type": "D",
"date_account_opened": "20170119",
"installment_due_date": "20180119",
"performing_indicator": "B",
"original_amount": "100000000",
"currency_facility": "KES",
"current_balance_kes": "100000000",
"current_balance": "9614385",
"overdue_balance": "1053",
"overdue_date": "20171219",
"days_arrears": "224",
"installment_arrears": "7",
"account_status": "F",
"account_status_date": "20170119",
"account_closure_reason": "",
"repayment_period": "12",
"deferred_payment_date": "",
"deferred_payment_amount": "0",
"payment_frequency": "M",
"disbursement_date": "20170119",
"next_installment_amount": "100",
"latest_payment_date": "20180727",
"last_payment_amount": "4980100",

Page | 11
"security_type": "s"
},
{
"registered_name": "ABC SERVICE STATION",
"trading_name": "ABC SERVICE STATION",
"reg_date": "19940316",
"reg_number": "C.123456 ",
"prev_reg_no": "0",
"nationality": "KE",
"client_no": "147852369",
"account_no": "963123456987",
"old_account_no": "",
"company_type": "K",
"industry_code": "012",
"annual_turnover": "0",
"pin_no": "0",
"vat_no": "0",
"number_of_shares": "1",
"trading_status": "002",
"trading_status_date": "20101119",
"main_phone": "25400000",
"other_phone": "25400000",
"postal_address1": "OFF ITEN ROAD",
"postal_address2": "OFF ITEN ROAD",
"town": "NAIROBI",
"country": "KE",
"post_code": "30100",
"physical_address1": "OFF ITEN ROAD",
"physical_address2": "4167",
"plot_no": "0",
"physical_location_town": "NAIROBI",
"physical_location_country": "KE",
"lenders_reg_name": "XYZ BANK",
"lenders_trading_name": "XYZ BANK",
"lenders_branch_name": "XYZ HQ",
"lenders_branch_code": "B003077",
"account_indicator": "J",
"account_holder_type": "A",
"account_product_type": "D",
"date_account_opened": "20101119",
"installment_due_date": "20131118",
"performing_indicator": "B",
"original_amount": "100000000",
"currency_facility": "KES",
"current_balance_kes": "100000000",
"current_balance": "237490",
"overdue_balance": "498",

Page | 12
"overdue_date": "20130819",
"days_arrears": "1807",
"installment_arrears": "60",
"account_status": "F",
"account_status_date": "20101119",
"account_closure_reason": "",
"repayment_period": "36",
"deferred_payment_date": "",
"deferred_payment_amount": "0",
"payment_frequency": "M",
"disbursement_date": "20101119",
"next_installment_amount": "100",
"latest_payment_date": "20130723",
"last_payment_amount": "14784045",
"security_type": "S"
}
]
}'

Sample JSON Response

{
"success":true,
"has_error":false,
"api_code":1010,
"api_code_description":"Data Submitted Successful",
"trx_id":"PREG-QTQY-20190227"
}
Sample JSON Fail Response

{
"success":false,
"has_error":true,
"api_code":1000,
"api_code_description":"reason for failure described here",
"trx_id":"f4fe8309-f39f-11e8-9683-55658ca4e102"
}

Page | 13
1. Monthly Submission - Template Version 3
i. Individual Consumer, Employer & Account (CE)
CE JSON Request Parameters

{
"data_ref":"CE",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_closure_reason":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"client_number":"string",
"consumer_email":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"date_at_physical_address":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"dob":"string",
"employer_name":"string",
"employment_date":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"home_telephone_number":"string",
"industry_type":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",

Page | 14
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"location_country":"string",
"location_town":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"original_amount":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"overdue_balance":"string",
"overdue_date":"string",
"payment_frequency":"string",
"performing_npl_indicator":"string",
"physical_address1":"string",
"physical_address2":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"postal_location_country":"string",
"postal_location_town":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"repayment_period":"string",
"salary_band":"string",
"salutation":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"security_type":"string",
"surname":"string",
"work_telephone_number":"string"
},
{
"account_closure_reason":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"client_number":"string",
"consumer_email":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",

Page | 15
"date_at_physical_address":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"dob":"string",
"employer_name":"string",
"employment_date":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"home_telephone_number":"string",
"industry_type":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"location_country":"string",
"location_town":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"original_amount":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"overdue_balance":"string",
"overdue_date":"string",
"payment_frequency":"string",
"performing_npl_indicator":"string",
"physical_address1":"string",
"physical_address2":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"postal_location_country":"string",
"postal_location_town":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"repayment_period":"string",
"salary_band":"string",

Page | 16
"salutation":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"security_type":"string",
"surname":"string",
"work_telephone_number":"string"
}

]
}

ii. Non Individual Consumer & Account (CI)

CI JSON Request Parameters

{
"data_ref":"CI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_closure_reason":"string",
"account_holder_type":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"annual_turnover_band":"string",
"client_number":"string",
"company_type":"string",
"country":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"industry_code":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",

Page | 17
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"main_telephone_number":"string",
"nationality":"string",
"number_of_shares":"string",
"original_amount":"string",
"other_telephone_number":"string",
"overdue_balance":"string",
"overdue_date":"string",
"payment_frequency":"string",
"performing_npl_indicator":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"registered_name":"string",
"registration_date":"string",
"registration_number":"string",
"repayment_period":"string",
"security_type":"string",
"town":"string",
"trading_name":"string",
"trading_status":"string",
"trading_status_date":"string",
"vat_number":"string"
},
{
"account_closure_reason":"string",
"account_holder_type":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"annual_turnover_band":"string",
"client_number":"string",
"company_type":"string",

Page | 18
"country":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"industry_code":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"main_telephone_number":"string",
"nationality":"string",
"number_of_shares":"string",
"original_amount":"string",
"other_telephone_number":"string",
"overdue_balance":"string",
"overdue_date":"string",
"payment_frequency":"string",
"performing_npl_indicator":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"registered_name":"string",
"registration_date":"string",
"registration_number":"string",
"repayment_period":"string",
"security_type":"string",
"town":"string",
"trading_name":"string",
"trading_status":"string",
"trading_status_date":"string",
"vat_number":"string"
}

Page | 19
]
}

iii. Credit Application (CA)

CA JSON Request Parameters

{
"data_ref":"CA",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_number":"string",
"application_amount":"string",
"application_currency":"string",
"application_date":"string",
"application_decline_reason_code":"string",
"application_no":"string",
"application_status":"string",
"application_status_date":"string",
"application_status_update_reason":"string",
"application_type":"string",
"client_number":"string",
"facility_application_type":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loan_term":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"product_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string"
},
{
"account_number":"string",
"application_amount":"string",
"application_currency":"string",
"application_date":"string",

Page | 20
"application_decline_reason_code":"string",
"application_no":"string",
"application_status":"string",
"application_status_date":"string",
"application_status_update_reason":"string",
"application_type":"string",
"client_number":"string",
"facility_application_type":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loan_term":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"product_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string"
}
]
}

iv. Collateral Register (CR)

CR JSON Request Parameters

{
"data_ref":"CR",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_number":"string",
"client_number":"string",
"collateral_currency":"string",
"collateral_expiry_date":"string",
"collateral_forced_sale_value":"string",
"collateral_reference_number":"string",
"collateral_type":"string",
"collateral_valuation_amount":"string",
"last_evaluation_date":"string",

Page | 21
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"multiple_shared_collateral":"string",
"next_value_date":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"portion_shared_collateral":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"recovery_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"shared_collateral":"string",
"vat_number":"string"
},
{
"account_number":"string",
"client_number":"string",
"collateral_currency":"string",
"collateral_expiry_date":"string",
"collateral_forced_sale_value":"string",
"collateral_reference_number":"string",
"collateral_type":"string",
"collateral_valuation_amount":"string",
"last_evaluation_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"multiple_shared_collateral":"string",
"next_value_date":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"portion_shared_collateral":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"recovery_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"shared_collateral":"string",
"vat_number":"string"
}
]
}

Page | 22
v. Stakeholder Information (SI)
SI JSON Request Parameters

{
"data_ref":"SI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_number":"string",
"client_number":"string",
"company_registration_number":"string",
"country":"string",
"dob_or_date_of_reg":"string",
"email":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"home_telephone_number":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"percent_shares_in_company":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_address3":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"salutation":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"stakeholder_type":"string",
"surname":"string",
"town":"string",

Page | 23
"vat_number":"string",
"work_telephone_number":"string"
},
{
"account_number":"string",
"client_number":"string",
"company_registration_number":"string",
"country":"string",
"dob_or_date_of_reg":"string",
"email":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"home_telephone_number":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"percent_shares_in_company":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_address3":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"salutation":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"stakeholder_type":"string",
"surname":"string",
"town":"string",
"vat_number":"string",
"work_telephone_number":"string"
}
]
}

Page | 24
vi. Guarantor Information(GI) JSON
GI JSON Request Parameters

{
"data_ref":"GI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_number":"string",
"client_number":"string",
"country":"string",
"dob_or_reg_date":"string",
"employee_name":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"group_name":"string",
"guarantee_limit":"string",
"guarantee_type":"string",
"guarantor_relationship":"string",
"home_telephone_number":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"salary_band":"string",

Page | 25
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"surname":"string",
"town":"string",
"work_telephone_number":"string"
},
{
"account_number":"string",
"client_number":"string",
"country":"string",
"dob_or_reg_date":"string",
"employee_name":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"group_name":"string",
"guarantee_limit":"string",
"guarantee_type":"string",
"guarantor_relationship":"string",
"home_telephone_number":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"salary_band":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"surname":"string",
"town":"string",
"work_telephone_number":"string"
}

Page | 26
]
}

vii. Bounced Cheque Information (BC)

BC JSON Request Parameters

{
"data_ref":"BC",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_number":"string",
"account_status":"string",
"branch_code_on_cheque":"string",
"cheque_account_type":"string",
"cheque_amount":"string",
"cheque_bounce_date":"string",
"cheque_bounce_reason_code":"string",
"cheque_currency":"string",
"cheque_date":"string",
"cheque_number":"string",
"client_number":"string"
},
{
"account_number":"string",
"account_status":"string",
"branch_code_on_cheque":"string",
"cheque_account_type":"string",
"cheque_amount":"string",
"cheque_bounce_date":"string",
"cheque_bounce_reason_code":"string",
"cheque_currency":"string",
"cheque_date":"string",
"cheque_number":"string",
"client_number":"string"
},
{
"account_number":"string",
"account_status":"string",
"branch_code_on_cheque":"string",
"cheque_account_type":"string",

Page | 27
"cheque_amount":"string",
"cheque_bounce_date":"string",
"cheque_bounce_reason_code":"string",
"cheque_currency":"string",
"cheque_date":"string",
"cheque_number":"string",
"client_number":"string"
}
]
}

viii. Fraudulent Activity (FA)

FA JSON Request Parameters

{
"data_ref":"FA",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"string",
"callback_url":"string",
"data":[
{
"account_number":"string",
"amount":"string",
"client_number":"string",
"currency_code":"string",
"forensic_information":"string",
"fraud_incident_date":"string",
"fraud_report_date":"string",
"fraud_status":"string",
"fraud_type":"string",
"incident_details":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loss_amount":"string"
},
{
"account_number":"string",
"amount":"string",
"client_number":"string",
"currency_code":"string",
"forensic_information":"string",
"fraud_incident_date":"string",

Page | 28
"fraud_report_date":"string",
"fraud_status":"string",
"fraud_type":"string",
"incident_details":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loss_amount":"string"
},
{
"account_number":"string",
"amount":"string",
"client_number":"string",
"currency_code":"string",
"forensic_information":"string",
"fraud_incident_date":"string",
"fraud_report_date":"string",
"fraud_status":"string",
"fraud_type":"string",
"incident_details":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loss_amount":"string"
},
{
"account_number":"string",
"amount":"string",
"client_number":"string",
"currency_code":"string",
"forensic_information":"string",
"fraud_incident_date":"string",
"fraud_report_date":"string",
"fraud_status":"string",
"fraud_type":"string",
"incident_details":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loss_amount":"string"
}
]
}

Page | 29
2. Monthly Submission - Template Version 4
i. Individual Consumer, Employer & Account (CE)
CE JSON Request Parameters

{
"data_ref":"CE",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_closure_reason":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"client_number":"string",
"consumer_email":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"dob":"string",
"employer_name":"string",
"employment_date":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"group_id":"string",
"home_telephone_number":"string",
"income_amount":"string",
"industry_type":"string",
"installment_amount":"string",
"installment_arrears":"string",

Page | 30
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"location_country":"string",
"location_town":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"old_account_number":"string",
"original_amount":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"overdue_balance":"string",
"overdue_date":"string",
"passport_country_code":"string",
"payment_frequency":"string",
"physical_address1":"string",
"physical_address2":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"postal_location_country":"string",
"postal_location_town":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"prudential_risk_classification":"string",
"repayment_period":"string",
"residence_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"security_type":"string",
"surname":"string",
"trading_as":"string",
"work_telephone_number":"string"
},
{
"account_closure_reason":"string",
"account_indicator":"string",
"account_number":"string",

Page | 31
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"client_number":"string",
"consumer_email":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"dob":"string",
"employer_name":"string",
"employment_date":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"group_id":"string",
"home_telephone_number":"string",
"income_amount":"string",
"industry_type":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"location_country":"string",
"location_town":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"old_account_number":"string",
"original_amount":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"overdue_balance":"string",
"overdue_date":"string",

Page | 32
"passport_country_code":"string",
"payment_frequency":"string",
"physical_address1":"string",
"physical_address2":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"postal_location_country":"string",
"postal_location_town":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"prudential_risk_classification":"string",
"repayment_period":"string",
"residence_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"security_type":"string",
"surname":"string",
"trading_as":"string",
"work_telephone_number":"string"
}
]
}

ii. Non Individual Consumer & Account (CI)

CI JSON Request Parameters

{
"data_ref":"CI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_closure_reason":"string",
"account_holder_type":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",

Page | 33
"account_status_date":"string",
"current_balance_kes":"string",
"annual_turnover":"string",
"client_number":"string",
"company_type":"string",
"country":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"industry_code":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"main_telephone_number":"string",
"nationality":"string",
"number_of_shares":"string",
"old_account_number":"string",
"original_amount":"string",
"other_telephone_number":"string",
"overdue_balance":"string",
"overdue_date":"string",
"payment_frequency":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"prudential_risk_classification":"string",
"registered_name":"string",
"registration_date":"string",

Page | 34
"registration_number":"string",
"repayment_period":"string",
"security_type":"string",
"town":"string",
"trading_name":"string",
"trading_status":"string",
"trading_status_date":"string",
"vat_number":"string"
},
{
"account_closure_reason":"string",
"account_holder_type":"string",
"account_indicator":"string",
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"annual_turnover":"string",
"client_number":"string",
"company_type":"string",
"country":"string",
"currency_facility":"string",
"current_balance":"string",
"date_account_opened":"string",
"days_arrears":"string",
"deferred_payment_amount":"string",
"deferred_payment_date":"string",
"disbursement_date":"string",
"industry_code":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"main_telephone_number":"string",
"nationality":"string",
"number_of_shares":"string",
"old_account_number":"string",
"original_amount":"string",
"other_telephone_number":"string",

Page | 35
"overdue_balance":"string",
"overdue_date":"string",
"payment_frequency":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"prudential_risk_classification":"string",
"registered_name":"string",
"registration_date":"string",
"registration_number":"string",
"repayment_period":"string",
"security_type":"string",
"town":"string",
"trading_name":"string",
"trading_status":"string",
"trading_status_date":"string",
"vat_number":"string"
}
]
}

Page | 36
iii. Credit Application (CA)
CA JSON Request Parameters

{
"data_ref":"CA",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"application_amount":"string",
"application_currency":"string",
"application_date":"string",
"application_decline_reason_codes":"string",
"application_no":"string",
"application_status":"string",
"application_status_date":"string",
"client_number":"string",
"client_type":"string",
"facility_application_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loan_term":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"product_type":"string",
"registered_name":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"surname":"string",
"trading_name":"string"
},

Page | 37
{
"account_number":"string",
"application_amount":"string",
"application_currency":"string",
"application_date":"string",
"application_decline_reason_codes":"string",
"application_no":"string",
"application_status":"string",
"application_status_date":"string",
"client_number":"string",
"client_type":"string",
"facility_application_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loan_term":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"product_type":"string",
"registered_name":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"surname":"string",
"trading_name":"string"
}
]
}

Page | 38
iv. Collateral Register (CR)
CR JSON Request Parameters

{
"data_ref":"CR",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"client_number":"string",
"collateral_currency":"string",
"collateral_expiry_date":"string",
"collateral_forced_sale_value":"string",
"collateral_reference_number":"string",
"collateral_type":"string",
"collateral_valuation_amount":"string",
"last_evaluation_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"multiple_shared_collateral":"string",
"next_value_date":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"portion_shared_collateral":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"recovery_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"shared_collateral":"string",
"vat_number":"string"
},
{
"account_number":"string",
"client_number":"string",
"collateral_currency":"string",

Page | 39
"collateral_expiry_date":"string",
"collateral_forced_sale_value":"string",
"collateral_reference_number":"string",
"collateral_type":"string",
"collateral_valuation_amount":"string",
"last_evaluation_date":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"multiple_shared_collateral":"string",
"next_value_date":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"portion_shared_collateral":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"recovery_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"shared_collateral":"string",
"vat_number":"string"
}

]
}

v. Stakeholder Information (SI)

SI JSON Request Parameters

{
"data_ref":"SI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"client_number":"string",

Page | 40
"company_name":"string",
"company_registration_number":"string",
"country":"string",
"dob_or_date_of_reg":"string",
"email":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"home_telephone_number":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"percent_shares_in_company":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_address3":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"stakeholder_type":"string",
"surname":"string",
"town":"string",
"vat_number":"string",
"work_telephone_number":"string"
},

{
"account_number":"string",
"client_number":"string",
"company_name":"string",
"company_registration_number":"string",
"country":"string",
"dob_or_date_of_reg":"string",
"email":"string",
"forename1":"string",

Page | 41
"forename2":"string",
"forename3":"string",
"gender":"string",
"home_telephone_number":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"percent_shares_in_company":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_address3":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"pin_number":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"previous_registration_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"stakeholder_type":"string",
"surname":"string",
"town":"string",
"vat_number":"string",
"work_telephone_number":"string"
}
]
}

vi. Guarantor Information(GI)

GI JSON Request Parameters

{
"data_ref":"GI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",

Page | 42
"callback_url":"string",
"data":[
{
"client_number":"string",
"company_name":"string",
"country":"string",
"dob_or_reg_date":"string",
"email":"string",
"employee_name":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"group_name":"string",
"guarantee_limit":"string",
"guarantee_type":"string",
"guarantor_relationship":"string",
"home_telephone_number":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"salary_band":"string",
"secondary_id_doc":"string",
"secondary_id_doc_no":"string",
"surname":"string",
"town":"string",
"work_telephone_number":"string"
},

Page | 43
{
"client_number":"string",
"company_name":"string",
"country":"string",
"dob_or_reg_date":"string",
"email":"string",
"employee_name":"string",
"employment_type":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"group_name":"string",
"guarantee_limit":"string",
"guarantee_type":"string",
"guarantor_relationship":"string",
"home_telephone_number":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"marital_status":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_location_country":"string",
"physical_location_town":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"salary_band":"string",
"secondary_id_doc":"string",
"secondary_id_doc_no":"string",
"surname":"string",
"town":"string",
"work_telephone_number":"string"
}
]
}

Page | 44
vii. Bounced Cheque (BC)
BC JSON Request Parameters
{
"data_ref":"BC",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"cheque_account_type":"string",
"cheque_amount":"string",
"cheque_current_balance_kes":"string",
"cheque_bounce_date":"string",
"cheque_bounce_reason_code":"string",
"cheque_branch_code":"string",
"cheque_currency":"string",
"cheque_date":"string",
"cheque_number":"string",
"client_number":"string",
"client_type":"string",
"company_name":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"loan_account":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"surname":"string"
},
{
"account_number":"string",
"cheque_account_type":"string",
"cheque_amount":"string",
"cheque_current_balance_kes":"string",
"cheque_bounce_date":"string",
"cheque_bounce_reason_code":"string",
"cheque_branch_code":"string",
"cheque_currency":"string",
"cheque_date":"string",
"cheque_number":"string",
"client_number":"string",
"client_type":"string",
"company_name":"string",

Page | 45
"forename1":"string",
"forename2":"string",
"forename3":"string",
"loan_account":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"surname":"string"
}
]
}

viii. Fraudulent Activity (FA)

FA JSON Request Parameters

{
"data_ref":"FA",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"amount":"string",
"current_balance_kes":"string",
"client_number":"string",
"currency_code":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"forensic_information":"string",
"fraud_incident_date":"string",
"fraud_report_date":"string",
"fraud_type":"string",
"incident_details":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loss_amount":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",

Page | 46
"surname":"string"
},
{
"account_number":"string",
"amount":"string",
"current_balance_kes":"string",
"client_number":"string",
"currency_code":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"forensic_information":"string",
"fraud_incident_date":"string",
"fraud_report_date":"string",
"fraud_type":"string",
"incident_details":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"loss_amount":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"surname":"string"
}
]
}

ix. Group Guarantee (GG)

GG JSON Request Parameters

{
"data_ref":"GG",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"M",
"template_version":"4",
"callback_url":"string",
"data":[
{
"client_number":"string",
"forename1":"string",

Page | 47
"forename2":"string",
"forename3":"string",
"group_id":"string",
"group_name":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"member_status":"string",
"member_status_date":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"sub_group_id":"string",
"sub_group_name":"string",
"surname":"string"
},
{
"client_number":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"group_id":"string",
"group_name":"string",
"lenders_branch_code":"string",
"lenders_branch_name":"string",
"lenders_registered_name":"string",
"lenders_trading_name":"string",
"member_status":"string",
"member_status_date":"string",
"other_id_doc_no":"string",
"other_id_doc_type":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"secondary_id_doc_no":"string",
"secondary_id_doc_type":"string",
"sub_group_id":"string",
"sub_group_name":"string",
"surname":"string"
}

Page | 48
]
}

3. Daily Updates - Template Version 4

i. Daily Payment Information (DP)
DP JSON Request Parameters

{
"data_ref":"DP",
"institution_ref":"string",
"is_final_submission":boolean,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"account_status":"string",
"client_type":"string",
"company_name":"string",
"currency_facility":"string",
"current_balance":"string",
"days_arrears":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"installment_arrears":"string",
"original_amount":"string",
"payment_amount":"string",
"payment_date":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"snapshot_date":"string",
"surname":"string"
},

{
"account_number":"string",
"account_status":"string",
"client_type":"string",
"company_name":"string",
"currency_facility":"string",

Page | 49
"current_balance":"string",
"days_arrears":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"installment_arrears":"string",
"original_amount":"string",
"payment_amount":"string",
"payment_date":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"snapshot_date":"string",
"surname":"string"
}
]
}

ii. Mobile Facilities (MF)

MF JSON Request Parameters

{
"data_ref":"MF",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"client_number":"string",
"currency_facility":"string",
"current_balance":"string",
"days_arrears":"string",
"disbursement_date":"string",
"dob":"string",
"forename1":"string",
"forename2":"string",

Page | 50
"forename3":"string",
"gender":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"original_amount":"string",
"overdue_balance":"string",
"overdue_date":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"prudential_risk_classification":"string",
"repayment_period":"string",
"surname":"string",
"trading_as":"string"
},
{
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"account_status_date":"string",
"current_balance_kes":"string",
"client_number":"string",
"currency_facility":"string",
"current_balance":"string",
"days_arrears":"string",
"disbursement_date":"string",
"dob":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"gender":"string",
"installment_amount":"string",
"installment_arrears":"string",
"installment_due_date":"string",
"latest_payment_amount":"string",
"latest_payment_date":"string",
"mobile_telephone_number":"string",
"nationality":"string",
"original_amount":"string",
"overdue_balance":"string",
"overdue_date":"string",

Page | 51
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"prudential_risk_classification":"string",
"repayment_period":"string",
"surname":"string",
"trading_as":"string"
}
]
}

iii. Historical Credit Information (FC)

FC JSON Request Parameters

{
"data_ref":"FC",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"additional_info":"string",
"client_type":"string",
"currency_facility":"string",
"current_balance":"string",
"days_arrears":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"installment_amount":"string",
"installment_arrears":"string",
"latest_payment_date":"string",
"original_amount":"string",
"overdue_balance":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"prudential_risk_classification":"string",
"registered_name":"string",
"snapshot_date":"string",
"surname":"string",
"trading_name":"string"
},

Page | 52
{
"account_number":"string",
"account_product_type":"string",
"account_status":"string",
"additional_info":"string",
"client_type":"string",
"currency_facility":"string",
"current_balance":"string",
"days_arrears":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"installment_amount":"string",
"installment_arrears":"string",
"latest_payment_date":"string",
"original_amount":"string",
"overdue_balance":"string",
"pin_number":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"prudential_risk_classification":"string",
"registered_name":"string",
"snapshot_date":"string",
"surname":"string",
"trading_name":"string"
}

]
}

iv. Contact Upload (CU)

CU JSON Request Parameters

{
"data_ref":"CU",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"client_type":"string",

Page | 53
"company_name":"string",
"email":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"home_telephone_number":"string",
"location_country":"string",
"location_town":"string",
"mobile_telephone_number":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_address_date":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"postal_location_country":"string",
"postal_location_town":"string",
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"snapshot_date":"string",
"surname":"string",
"work_telephone_number":"string"
},

{
"account_number":"string",
"client_type":"string",
"company_name":"string",
"email":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"home_telephone_number":"string",
"location_country":"string",
"location_town":"string",
"mobile_telephone_number":"string",
"physical_address1":"string",
"physical_address2":"string",
"physical_address_date":"string",
"plot_number":"string",
"post_code":"string",
"postal_address1":"string",
"postal_address2":"string",
"postal_location_country":"string",
"postal_location_town":"string",

Page | 54
"primary_id_doc_no":"string",
"primary_id_doc_type":"string",
"snapshot_date":"string",
"surname":"string",
"work_telephone_number":"string"
}
]
}

v. Delink Id’s (DI)

DI JSON Request Parameters

{
"data_ref":"DI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"primary_id_doc_no_delink":"string",
"primary_id_doc_no_link":"string",
"primary_id_doc_type_delink":"string",
"primary_id_doc_type_link":"string",
"surname":"string"
},
{
"account_number":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"primary_id_doc_no_delink":"string",
"primary_id_doc_no_link":"string",
"primary_id_doc_type_delink":"string",
"primary_id_doc_type_link":"string",
"surname":"string"
}
]
}

Page | 55
vi. Link-Delink Id’s (LI)
LI JSON Request Parameters

{
"data_ref":"LI",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"function":"string",
"id_doc_no1":"string",
"id_doc_no2":"string",
"id_doc_type1":"string",
"id_doc_type2":"string"
},
{
"function":"string",
"id_doc_no1":"string",
"id_doc_no2":"string",
"id_doc_type1":"string",
"id_doc_type2":"string"
},
{
"function":"string",
"id_doc_no1":"string",
"id_doc_no2":"string",
"id_doc_type1":"string",
"id_doc_type2":"string"
}
]
}

Page | 56
vii. Accounts Merger (ME)
ME JSON Request Parameters

{
"data_ref":"ME",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"forename1":"string",
"forename2":"string",
"forename3":"string",
"id_doc_no":"string",
"id_doc_type":"string",
"new_account_number":"string",
"old_account_number":"string",
"surname":"string"
},
{
"forename1":"string",
"forename2":"string",
"forename3":"string",
"id_doc_no":"string",
"id_doc_type":"string",
"new_account_number":"string",
"old_account_number":"string",
"surname":"string"
}
]
}

Page | 57
viii. Deletion (DE)
DE JSON Request Parameters

{
"data_ref":"DE",
"institution_ref":"string",
"is_final_submission":true,
"submission_date":"yyyyMMdd",
"submission_type":"D",
"template_version":"4",
"callback_url":"string",
"data":[
{
"account_number":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"function_type":"string",
"id_doc_no":"string",
"id_doc_type":"string",
"new_day_arrears":"string",
"snapshot_date":"string",
"surname":"string"
},
{
"account_number":"string",
"forename1":"string",
"forename2":"string",
"forename3":"string",
"function_type":"string",
"id_doc_no":"string",
"id_doc_type":"string",
"new_day_arrears":"string",
"snapshot_date":"string",
"surname":"string"
}
]
}

Page | 58
4.2.3. Get File Status
4.2.3.1. Get Submitted Files
This API endpoint is used to fetch list of files/JSON submitted to the bureau. It gives a summary
of each file submitted. If request_code (Trx_id returned after successfully submitting data) is
provided as one of the parameters, the API will return a summary for only that single submission.

Note: The response has request_data_type parameter that you can use to identify the type of
submission that was made. The request_data_type will be “001” if the submission was JSON and
“002” if it was a CSV file.

HTTP Method: GET

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/upload/requests

Sample Request

curl -X GET \

'https://192.168.20.188:1234/api/v1/datasubmission/upload/requests?submission_type=M' \

-H 'Authorization: Bearer
eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZGF0YS1zdWJtaXNzaW9uLWFwaSJdLCJzY29wZSI6WyJyZWFkIiwid3Jp
dGUiXSwiZXhwIjoxNTUxNDI0NDEyLCJhdXRob3JpdGllcyI6WyJST0xFXzE2Il0sImp0aSI6IjBlMGJkNTRlLWM5
ODMtNDY1My1iNjY3LTBmNzQxOTEzNTEzOCIsImNsaWVudF9pZCI6IlFyTW5FOWJGQ2l1THR1cFE1S1BFb1
F5U2JQWGpjS3NQIn0.DJJZe2mHaSZHIiZ-E_CP5FFAp7pqGMp-yMwkd-Y7VJk' \

-H 'Content-Type: application/json' \

-H 'cache-control: no-cache'

Request Parameters

Parameter Type Optional Description

Transaction ID (trx_id) obtained after submitting
request_code string yes
data. Gets summary for that single submission
Type of submission (D/M). Filters results to the
submission_type string yes
submission specified
page string yes Page to retrieve

page_size string yes Number of items per page

Page | 59
Sample JSON Response

{
"success":true,
"has_error":false,
"api_code":1000,
"api_code_description":"Details fetched Successfully",
"message":null,
"trx_id":"47622af7-3b32-11e9-ad45-d54374a9b630",
"data":[
{
"submission_type":"M",
"request_code":"IY72-FYFW-20190228",
"created_date":"2019-02-28T10:15:52.424+0300",
"request_data_type":"002"
},
{
"submission_type":"M",
"request_code":"CVYH-EYVA-20190228",
"created_date":"2019-02-28T09:51:47.393+0300",
"request_data_type":"001"
},
{
"submission_type":"M",
"request_code":"PREG-QTQY-20190227",
"created_date":"2019-02-27T18:39:42.244+0300",
"request_data_type":"001"
},
{
"submission_type":"M",
"request_code":"FQHM-T9PE-20190227",
"created_date":"2019-02-27T18:02:43.585+0300",
"request_data_type":"002"
},
{
"submission_type":"M",
"request_code":"SEYJ-NXM9-20190227",
"created_date":"2019-02-27T16:39:02.147+0300",
"request_data_type":"002"
},
{
"submission_type":"M",
"request_code":"L38T-PFAS-20190227",
"created_date":"2019-02-27T15:11:06.065+0300",
"request_data_type":"001"
},
{
"submission_type":"M",
"request_code":"8Q7P-MJIM-20190227",

Page | 60
"created_date":"2019-02-27T15:05:45.791+0300",
"request_data_type":"001"
},
{
"submission_type":"M",
"request_code":"1UTI-2LBJ-20190226",
"created_date":"2019-02-26T15:19:32.616+0300",
"request_data_type":"002"
}
],
"meta":{
"first":true,
"last":false,
"number":0,
"size":10,
"sort":{
"sorted":true,
"unsorted":false,
"empty":false
},
"number_of_elements":10,
"total_pages":204,
"total_elements":2036
}
}

Page | 61
4.2.3.2. Get Validation Status of a file
This API endpoint is used to get the validation status/results of a single submission file. You
need to pass the request_code (trx_id) for the submission.

Note: The data parameter on the response will vary depending on how a submission was done
i.e. JSON or CSV. You need to know the submission format before making a request in order to
handle appropriately the response to returned. You can tell the submission format from the
request_data_type parameter in the summary returned in the “Get Submitted Files” endpoint
above

HTTP Method: GET

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/upload/file

Sample Request

curl -X GET \

'https://api.metropol.co.ke:1234/api/v1/datasubmission/upload/file?request_code=FDBY-PWHI-
20190115' \

-H 'Accept: application/json' \

-H 'Authorization: Bearer
eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZGF0YS1zdWJtaXNzaW9uLWFwaSJdLCJzY29wZSI6WyJyZWFkIiwid3Jp
dGUiXSwiZXhwIjoxNTUxNDI0NDEyLCJhdXRob3JpdGllcyI6WyJST0xFXzE2Il0sImp0aSI6IjBlMGJkNTRlLWM5
ODMtNDY1My1iNjY3LTBmNzQxOTEzNTEzOCIsImNsaWVudF9pZCI6IlFyTW5FOWJGQ2l1THR1cFE1S1BFb1
F5U2JQWGpjS3NQIn0.DJJZe2mHaSZHIiZ-E_CP5FFAp7pqGMp-yMwkd-Y7VJk' \

-H 'cache-control: no-cache'

Request Parameters

Parameter Type Optional Description

Transaction ID (trx_id) obtained after submitting
request_code string no
data. Gets summary for that single submission

Page | 62
Sample JSON Response for request_data_type 002 (CSV Submission)

{
"success":true,
"has_error":false,
"api_code":1000,
"api_code_description":"Details fetched Successfully",
"message":null,
"trx_id":"997ff0f8-3b28-11e9-ad45-d304763bf61f",
"data":[
{
"validPartner":true,
"submittedBy":78,
"submissionType":null,
"reference_code":"4XIP-9OUX-20190115",
"template_version":"4",
"submission_date":20190101,
"file_size":16767431,
"file_name":"CRBBMCE20190101001.B041",
"status":9,
"records_count":38469,
"records_imported":null,
"records_passed":0,
"records_rejected":38469,
"error_count":38469,
"is_final_submission":true,
"download_url":"https://api.metropol.co.ke:1234/api/v1/datasubmissio
n/download/errorfile/CRBBMCE20190101001.B041.csv",
"file_url":"https://api.metropol.co.ke:1234/api/v1/datasubmission/do
wnload/file/CRBBMCE20190101001.B041",
"error_log_status":3
}
],
"meta":{
"first":true,
"last":true,
"number":0,
"size":10,
"sort":{
"sorted":true,
"unsorted":false,
"empty":false
},
"number_of_elements":1,
"total_pages":1,

Page | 63
"total_elements":1
}
}

Sample JSON Response for request_data_type 001 (JSON Submission)

{
"success":true,
"has_error":false,
"api_code":1000,
"api_code_description":"Details fetched Successfully",
"message":null,
"trx_id":"e1d98db2-3b34-11e9-8d38-1b00cc2ff9cc",
"data":[
{
"liveStatus":7,
"submissionType":null,
"reference_code":"CBCT-2YEE-20190228",
"template_version":"3",
"data_ref":"CE",
"is_final_submission":true,
"records_imported":null,
"records_count":4,
"empty_records":0,
"records_passed":0,
"records_rejected":4,
"error_count":null,
"download_url":null,
"error_log_status":null,
"status":6
}
],
"meta":{
"first":true,
"last":true,
"number":0,
"size":10,
"sort":{
"sorted":true,
"unsorted":false,
"empty":false
},
"number_of_elements":1,
"total_pages":1,
"total_elements":1

Page | 64
}
}

4.2.4. Fetching Error Logs

Fetching of error logs for CSV submitted files is different from fetching error logs for JSON
submitted files.

4.2.4.1. Fetch CSV Error Logs

The process of retrieving error logs for CSV submitted files involves:

1. Get validation status of the CSV file by calling /datasubmission/upload/file endpoint and
passing the request_code (trx_id). See Get Validation Status of a file
2. Invoke generation of error files by calling /datasubmission/error/generatelog endpoint
and passing the reference code (Obtained from the response in 1. above)
3. Call the /datasubmission/error/geterror endpoint to get the error log file and the
submitted file.

A. Generate CSV Error Log

This endpoint is used to generate error logs for CSV files uploaded. The reference_code linking
to a specified submission request is required in order to generate the error logs.

HTTP Method: POST

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/error/generatelog

Sample Request Header

curl -X POST \

'https://api.metropol.co.ke:1234/api/v1/datasubmission/error/generatelog?reference_code=WDFG-
DM1D-20190301\

-H 'Authorization: Bearer f6908009-2b3f-423c-9a5d-aed378116025' \

-H 'cache-control: no-cache'

Page | 65
Request Parameters

Parameter Type Optional Description

Reference code for returned from Get Validation
reference_code string no
Status of a file

Sample Response

{
"success":true,
"has_error":false,
"api_code":1010,
"api_code_description":"Submission Error Logs generation Invoked For Ref
erence Code : CBCT-2YEE-20190228",
"trx_id":"5c5d11e5-3b4b-11e9-9c66-ad59800cd4eb",
"data":{
"record_count":4,
"record_passed":0,
"record_rejected":4,
"error_count":null,
"template_version":"3",
"file_type":"CE",
"batch_file_type":null,
"reference_code":"CBCT-2YEE-20190228"
}
}

B. Get CSV Error Log

Use this endpoint to get the links to download the error log file and the original CSV file
submitted.

HTTP Method: GET

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/error/geterror

Page | 66
Sample Request Header

curl -X GET \

'https://api.metropol.co.ke:1234/api/v1/datasubmission/error/geterror?reference_code=WDFG-
DM1D-20190301' \

-H 'Accept: application/json' \

-H 'Authorization: Bearer
eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZGF0YS1zdWJtaXNzaW9uLWFwaSJdLCJzY29wZSI6WyJyZWFkIiwid3Jp
dGUiXSwiZXhwIjoxNTUxNzcyMTc0LCJhdXRob3JpdGllcyI6WyJST0xFXzE2Il0sImp0aSI6IjhjNzk1NzA2LTUwN
WEtNGY2NS05Mzg5LTlhZmE0NTQ5NjgwYiIsImNsaWVudF9pZCI6Ik8wNFdzNk9wYzl6VVd6d2k4MjhqQnd
ZTlQ2cGw3c3E2In0.iQ-fW2UHwzdcwBOjzF1e8SaDcohmGiRfL61FjjrnK9I' \

-H 'cache-control: no-cache'

Request Parameters

Parameter Type Optional Description

Reference code for returned from Get Validation
reference_code string no
Status of a file

Sample Response

{
"success":true,
"has_error":false,
"api_code":1010,
"api_code_description":"Submission Error Log Reference Code : WDFG-DM1D-
20190301",
"trx_id":"c225dad5-3c33-11e9-9c66-65938c2b366b",
"data":{
"validPartner":true,
"submittedBy":48,
"submissionType":"M",
"reference_code":"WDFG-DM1D-20190301",
"template_version":"3",
"submission_date":20190101,
"file_size":498,
"file_name":"CRBBCE20190101007.B068",
"status":6,
"records_count":1,
"records_imported":null,
"records_passed":1,
"records_rejected":0,
"error_count":null,

Page | 67
"is_final_submission":true,
"download_url":”https://api.metropol.co.ke:1234/api/v1/datasubmission
/downloadFile/FGO5-KIHW-20190304_CRBBCE20190101007.B068.csv”,
"file_url":null,
"error_log_status":1
}
}

4.2.4.2. Fetch JSON Error Log

The process of retrieving error logs for JSON submissions is as below:

A. Get validation status of the JSON File by calling /datasubmission/upload/file endpoint

and passing the request_code (trx_id). See Get Validation Status of a file
B. Call the /datasubmission/error/geterrorlist endpoint to get the error log file and the
submitted file.

A. Get JSON Error List

Use this endpoint to get a list of errors for the submitted JSON file. The endpoint returns the
error list for the provided reference code.

HTTP Method: GET

Test URL:

https://api.metropol.co.ke:PORT_NUMBER/API_VERSION/datasubmission/error/geterrorlist

Sample Request Header

curl -X GET \

'https://api.metropol.co.ke:1234/api/v1/datasubmission/error/geterrorlist?reference_code=3GVM-
9Z52-20190301' \

-H 'Accept: application/json' \

-H 'cache-control: no-cache'

Request Parameters

Parameter Type Optional Description

Reference code for returned from Get Validation
reference_code string no
Status of a file

Page | 68
Sample Response

{
"success":true,
"has_error":false,
"api_code":1010,
"api_code_description":"Submission Error Log request Code: 3GVM-9Z52-
20190301",
"trx_id":"650a3b78-3e61-11e9-ad8b-03f8a8fa0d0b",
"data":{
"content":[
{
"column_name":"amountKes",
"column_index":18,
"row_index":0,
"value_provided":"-10000",
"data_rule_id_type_id":1,
"error_description":"ENF157 Amount can not be negative",
"client_number":"123CLIENT",
"account_number":"AC555AC"
},
{
"column_name":"disbursementDate",
"column_index":28,
"row_index":0,
"value_provided":"20300305",
"data_rule_id_type_id":1,
"error_description":"ENF145 Date not in the future",
"client_number":"123CLIENT",
"account_number":"AC555AC"
},
{
"column_name":"prudentialRiskClassification",
"column_index":24,
"row_index":0,
"value_provided":"B",
"data_rule_id_type_id":1,
"error_description":"ENF193 If days in arrears are between 0-
30, prudential risk classification should be A",
"client_number":"123CLIENT",
"account_number":"AC555AC"
}
],
"pageable":{
"sort":{
"sorted":false,
"unsorted":true,

Page | 69
"empty":true
},
"pageSize":10,
"pageNumber":0,
"offset":0,
"paged":true,
"unpaged":false
},
"totalPages":1,
"totalElements":3,
"last":true,
"first":true,
"sort":{
"sorted":false,
"unsorted":true,
"empty":true
},
"number":0,
"numberOfElements":3,
"size":10,
"empty":false
}
}

4.2.5. Response Data to Call Back URL

Metropol Submission API requires callback URL to be provided when submitting data in JSON or
File. Below is a description of what is sent to the callback URL after a validation is completed.

Sample Callback Response Data

{
"request_code":"VNQI-P49Z-20190712",
"data":[
{
"reference_code":"CRB2-JLZO-20190712",
"template_version":"4",
"status":"Validated",
"record_count":1,
"records_passed":0,
"records_rejected":1
}
]
}

Page | 70
5. API Reference Codes
5.1. Submission Types

Submission Types
Code Description
M Monthly
D Daily Updates

5.2. Institution Refs

Institution Refs
Code Description
B Bank
D MFB
S SACCO
M MFI
L Leasing Companies

5.3. Response Codes

HTTP Response Codes

Code Description
400 Bad Request

401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
500 Internal Server Error – Problem with our server. Try again later.
503 Service Unavailable – Service temporarily offline for maintenance.
Try again later.

Page | 71
5.4. API Codes

API Codes
API_CODE Description
1000 Unsuccessful Request. Check error described in the
api_code_description

1010 Successful Request

5.5. Validation Status Codes

Validation Status Codes

Status Codes Description
1 Unprocessed Request

2 Invalid File Name

3 Valid File Name
5 Validating File
6 Validation Complete
7 No records found. (Zero records)
8 Generating Error Logs
9 Completed Generating Error Log
10 Invalid Partner/Institution Code

Page | 72
5.6. Submission Files Data Refs

5.6.1. Template v3 - Monthly Batch Data Refs

DST-V3 Monthly Batch Refs
Code Description
CE Individual Consumer, Employer & Account Information
CI Non-Individual Consumer & Account Information
GI Guarantor Information
BC Bounced Cheque Information
CA Credit application Information
SI Stake Holder Information
FA Fraudulent Activity
CR Collateral Register Information

5.6.2. Template v4 - Monthly Batch Data Refs

DST-V4 Monthly Batch Refs
Code Description
CE Individual Consumer, Employer & Account Information
CI Non-Individual Consumer & Account Information
GI Guarantor Information
BC Bounced Cheque Information
CA Credit application Information
SI Stake Holder Information
FA Fraudulent Activity
CR Collateral Register Information
GG Group Guarantee Information

5.6.3. Template v4 - Daily Batch Data Refs

DST-V4 Daily Batch Refs
Code Description
DP Daily Payment Information
MF New Mobile Facilities File
FC Historical Credit Information Update File
CU Contact Upload File
DI Delink-IDs File
LI Link-Delink Accounts File
ME Merging Accounts
DE Deletion File

Page | 73
6. Document Version
MCRB API: Document Version
Version Date Comment
1.0 Feb 28th 2019 Initial API document
Added sample data posted to client call back url on successful
1.1 July 12th 2019 validation of file
Updated MF file- changed “current_balance_kes” parameter
to “current_balance_kes”
1.2 Oct 7th 2019 Changed URL from dvt.metropol.co.ke to api.metropol.co.ke

Page | 74