Onboarding
This section describes the API for customer onboarding. It is recommended to read the document Onboard Your Customer to understand the onboarding process of Choice bank.
Create a new client
POST /onboarding/submitOnboardingRequest
<Use this endpoint to onboard a new client and submit its kyc information>
Parameters
userId
string
A unique string to identify the user in the partner system.
TRUE
firstName
string
First name of the onboarding customer
TRUE
middleName
string
middle name of the onboarding customer
FALSE
lastName
string
last name of the onboarding customer
TRUE
birthday
string
Date of Birth; yyyy-MM-dd
TRUE
address
string
Physical address of the onboarding customer
TRUE
gender
integer
0 - Female
1 - Male
TRUE
countryCode
string
The country code of the mobile, that the customer is using to onboard
TRUE
mobile
string
The mobile number that the customer is using to onboard
TRUE
email
string
Email address of the customer
FALSE
idType
string
Type of the document that the customer is using to onboard.
101 - (Kenya) National ID
102 - (Kenya) Alien ID
103 - Passport
TRUE
idNumber
string
ID Number of National ID/Passport/Alien ID
TRUE
kraPin
string
KRA PIN / Tax Number
TRUE
employmentStatus
string
Customer's work status.
A - Employee
B - Self employed
C - Unemployed
D - Employer
E - Student
F - Others
TRUE
monthlyIncome
string
Customer monthly income information.
A - Less than Ksh. 14,999
B - Ksh. 15,000-24,999
C - Ksh. 25,000-39,999
D - Ksh. 40,000-59,999
E - Ksh. 60,000-84,999
F - Above Ksh. 85,000
TRUE
businessIndustry
string
This field captures the industry the business is operating in. Please submit the number representing the business sector.
1 - Agriculture and Agribusiness
2 - Manufacturing and Processing
3 - Construction and Engineering
4 - Retail and Wholesale Trade
5 - Information and Communication Technology
6 - Tourism and Hospitality
7 - Health and Wellness Services
8 - Education and Training
9 - Financial Services
10 - Professional Services
11 - Creative Industries
12 - Renewable Energy and Environmental Conservation
13 - Transport and Logistics
14 - Food and Beverage
15 - Textiles and Apparel
16 - Automotive and Engineering Services
17 - Beauty and Personal Care
18 - Real Estate and Property Development
19 - Consulting and Business Services
20 - Social Enterprises and NGOs
21 - Others, please specify
FALSE
specifyIndustry
string
When businessIndustry == Others, please specify, this field is Mandatory.
FALSE
Response
{
"onboardingRequestId": "ONBOARD7695534567876"
}Upload client KYC document
POST /onboarding/uploadMedia
<Use this endpoint to submit onboarding client's media file, like its ID documents, selfie document>
Parameters
onboardingRequestId
string
The unique onboarding request id that was returned from Choice system.
TRUE
mediaBase64
integer
BASE64 text of the document file
TRUE
contentType
string
File type of the document.
It's either PDF or Image.
When this parameter value is not given, the default type will be used.
FALSE
Response
{
"code": "00000",
"msg": "Completed successfully"
}Query onboarding status
POST /onboarding/getOnboardingStatus
<Use this endpoint to query the onboarding status>
Parameters
userId
string
The unique string to identify the user in the partner system.
FALSE
onboardingRequestId
string
The unique onboarding request id that was returned from Choice system.
FALSE
mobile
string
The mobile number that the customer is using to onboard.
Use either one from userId / onboardingRequestId / mobile to query the onboarding status.
FALSE
Response
{
"onboardingRequestId": "ONBOARD2309LKSD90432",
"onboardingStatus": "Completed successfully"
}Query client KYC information
POST /onboarding/getUserKyc
<Use this endpoint to get the KYC information and its status>
Parameters
onboardingRequestId
string
The unique onboarding request id that was returned from Choice system.
TRUE
Response
{
"onboardingRequestId": "ONBOARD2309LKSD90432",
"baasChannelId": "", //This is your channel ID
"userId": "", //The unique user identifier in your system
"firstName": "Lily",
"middleName": "IMISA",
"lastName": "WAMBUI",
"gender": "0", //0-Female; 1-Male;
"nationality": "Kenya",
"idType": "", //101-(Kenya) National ID; 102-(Kenya) Alien ID; 103-Passport
"idNumber": "",
"birthday": "",
"address": "",
"countryCode": "", //country code for mobile number
"mobile": "",
"employmentStatus": "", //Please refer to Employment Status Enumeration
"monthlyIncome": "", //Please refer to Monthly Income Enumeration
"kraPin": "", //Kenya KRA PIN code or tax number from other countries
"businessIndustry": "",
"specifyIndustry": "",
"profileCheck": "", //0-Not Checked; 1-Submitted; 2-Validated; 3-Declined; 4-Processing;
"profileCheckResultCode": "",
"profileCheckResultText": "",
"createTime": "",
"updateTime": "",
"status": "", //1-Submitted; 2-Processing; 3-Passed; 4-Rejected;
//5-Account Closed; 9-Manual Reviewing
}Query client KYC media information
POST /onboarding/personal/getKycMediaList
<Use this endpoint to get client's kyc media information>
Parameters
onboardingRequestId
string
The unique onboarding request id that was returned from Choice system.
TRUE
Response
{
"mediaList": [
{
"mediaType": "",
"fileTypeId": "",
"mediaUrl": "",
}, {}
]
}Query client onboarding request ID
POST /onboarding/getOnboardingRequestId
<This endpoint allows you to get client's onboardingRequestId using its user ID or mobile number>
Parameters
userId
string
The unique string to identify the user in the partner system.
FALSE
mobile
string
User's mobile number / The mobile number that the user used to onboard
FALSE
Response
{
"onboardingRequestId": ""
}Last updated