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.
Initiate an SME Onboarding Request
POST /onboarding/business/applyForSmeOnboarding
<Use this endpoint to start onboarding an SME customer>
Parameters
userId
string
A unique string to identify the user in the partner system.
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.
When otpType == SMS, this is optional;
When otpType == EMAIL, this is mandatory.
FALSE
businessType
Integer
Business type of the SME customer that is to onboard.
1 - Sole Proprietorship
2 - Limited Liability Company
3 - Partnership
4 - NGO / CBO
TRUE
otpType
string
Onboard an SME requires OTP confirmation. This determins the type of OTP that they want to receive to do OTP confirmation and onboard.
Support values:
SMS
TRUE
Response
{
"onboardingRequestId": "ONBOARD7695534567876"
}Submit Basic Info - Sole Proprietorship
POST /onboarding/business/submitStoreOnboardingRequest
<Use this endpoint to onboard a new Sole Proprietorship SME customer and submit its kyc information>
Parameters
onboardingRequestId
string
A unique string generated by Choice to identify a certain onboarding request
TRUE
businessName
string
Business's name
TRUE
businessCerNum
string
Business certificate number
TRUE
firstName
string
First name of the onboarding business owner
TRUE
middleName
string
middle name of the onboarding business owner
FALSE
lastName
string
last name of the onboarding business owner
TRUE
birthday
string
Date of Birth of the business owner; yyyy-MM-dd
TRUE
gender
integer
0 - Female
1 - Male
TRUE
idNumber
string
ID Number of National ID/Passport/Alien ID
TRUE
kraPin
string
KRA PIN / Tax Number of the business (owner)
TRUE
kinFullName
string
The full name of the business owner's next kin
TRUE
kinRelationship
string
The relationship between the business owner and its next kin
TRUE
kinCountryCode
string
Country code of the business owner's next kin (mobile)
TRUE
kinMobile
string
Mobile number of the business owner's next kin
TRUE
businessAddress
string
Physical address of the onboarding business
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
TRUE
specifyIndustry
string
When businessIndustry == Others, please specify, this field is Mandatory.
FALSE
Response
{
"code": "00000",
"msg": "Completed successfully"
}Submit Basic Info - LLC
POST /onboarding/business/submitCompanyOnboardingRequest
<Use this endpoint to onboard a new Limited Liability Company SME customer and submit its kyc information>
Parameters
onboardingRequestId
string
A unique string generated by Choice to identify a certain onboarding request
TRUE
businessName
string
Business's name
TRUE
businessCerNum
string
Business certificate number
TRUE
kraPin
string
KRA PIN / Tax Number of the business
TRUE
operatingMode
integer
1 - Singly
2 - Either to sign
3 - Any Two to Sign
4 - All of Us Jointly
TRUE
businessAddress
string
Physical address of the onboarding business
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
TRUE
specifyIndustry
string
When businessIndustry == Others, please specify, this field is Mandatory.
FALSE
Response
{
"code": "00000",
"msg": "Completed successfully"
}Submit Basic Info - Partnership
POST /onboarding/business/submitPartnershipOnboardingRequest
<Use this endpoint to onboard a new Partnership SME customer and submit its kyc information>
Parameters
onboardingRequestId
string
A unique string generated by Choice to identify a certain onboarding request
TRUE
businessName
string
Business's name
TRUE
businessCerNum
string
Business certificate number
TRUE
kraPin
string
KRA PIN / Tax Number of the business
TRUE
operatingMode
integer
1 - Singly
2 - Either to sign
3 - Any Two to Sign
4 - All of Us Jointly
TRUE
businessAddress
string
Physical address of the onboarding business
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
TRUE
specifyIndustry
string
When businessIndustry == Others, please specify, this field is Mandatory.
FALSE
Response
{
"code": "00000",
"msg": "Completed successfully"
}Submit Basic Info - NGO / CBO
POST /onboarding/business/submitOrganisationOnboardingRequest
<Use this endpoint to onboard a new NGO / CBO SME customer and submit its kyc information>
Parameters
onboardingRequestId
string
A unique string generated by Choice to identify a certain onboarding request
TRUE
businessName
string
Business's name
TRUE
businessCerNum
string
Business certificate number
TRUE
kraPin
string
KRA PIN / Tax Number of the business
TRUE
operatingMode
integer
1 - Singly
2 - Either to sign
3 - Any Two to Sign
4 - All of Us Jointly
TRUE
businessAddress
string
Physical address of the onboarding business
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
TRUE
specifyIndustry
string
When businessIndustry == Others, please specify, this field is Mandatory.
FALSE
Response
{
"code": "00000",
"msg": "Completed successfully"
}Add Shareholders / Directors (Individual)
POST /onboarding/business/submitCompanyMember
<Use this endpoint to add the information of the company's individual type of shareholders/directors>
Parameters
onboardingRequestId
string
A unique string generated by Choice to identify a certain onboarding request
TRUE
idType
string
101 - (Kenya) National ID
102 - (Kenya) Alien ID
103 - Passport
TRUE
idNumber
string
ID number
TRUE
gender
integer
0 - Female
1 - Male
FALSE
email
string
Email address
FALSE
countryCode
string
country code
TRUE
mobile
string
mobile number
TRUE
firstName
string
First name of the shareholder / director
TRUE
middleName
string
Middle name of the shareholder / director
FALSE
lastName
string
Last name of the shareholder / director
TRUE
kraPin
string
KRA PIN / Tax Number of the shareholder / director
TRUE
idFrontSideFile
string
Base 64 string
TRUE
idFrontSideFileType
string
Image
FALSE
idBackSideFile
string
Base 64 string
FALSE
idBackSideFileType
string
Image
FALSE
selfieFile
string
Base 64 string
FALSE
selfieFileType
string
Image
FALSE
kraPinFile
string
Base 64 string
TRUE
kraPinFileType
string
Image
FALSE
Response
{
"memberId": "",
}Add Shareholders / Directors (Organization)
POST /onboarding/business/submitShareholderCompanyMember
<Use this endpoint to add the information of the company's organization type of shareholders/directors>
Parameters
onboardingRequestId
string
A unique string generated by Choice to identify a certain onboarding request
TRUE
registrationFile
string
Base 64 string
TRUE
registrationFileType
string
Image
TRUE
companyName
string
Company name
TRUE
Response
{
"companyId": "",
}Remove Shareholders / Directors
POST /onboarding/business/removeMember
<Use this endpoint to remove company's shareholders/directors>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
memberId
String
For individual type of shareholders/directors, it's the memberId; For organization type, it's companyId.
TRUE
memberType
Int
0 - Individual
1 - Organization
TRUE
Response
{
"code": "00000",
"msg": "Completed successfully",
}Upload Onboarding Media Materials
POST /onboarding/uploadMedia
<Use this endpoint to upload media materials for onboarding>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
mediaBase64
String
Base 64 string
TRUE
contentType
String
Image
FALSE
Response
{
"fileId": "",
}Remove Onboarding Media Materials
POST /onboarding/business/removeMedia
<Use this endpoint to remove the media materials that have been uploaded>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
fileId
String
The ID of the file that is to be removed
TRUE
Response
{
"code": "00000",
"msg": "Completed successfully",
}Submit / Pull Back Onboarding Request
POST /onboarding/submitOrPullBackRequest
<Use this endpoint to submit (send it for Bank Reviewing) or Pull Back (send it for further editing) the onboarding requests>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
action
String
0 - Pull Back
1 - Submit
TRUE
Response
{
"code": "00000",
"msg": "Completed successfully",
}Cancel Onboarding Request
POST /onboarding/cancelOnboardingRequest
<Use this endpoint to cancel the onboarding requests. If not actively cancelling it, the onboarding request will wait until its automatic cancelling time. Before OTP confirmation, it's 30 mins, after OTP confirmation, it's 72 hours.>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
Response
{
"code": "00000",
"msg": "Completed successfully",
}Query Onboarding Info - Sole Proprietor
POST /onboarding/business/getStoreOnboardingInfo
<Use this endpoint to query the onboarding information & materials for Sole Proprietorship type of SME>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
Response
{
"onboardingRequestId": "00000",
"smeName": "",
"businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO
"countryCode": "",
"mobile": "",
"email": "",
"krapin": "",
"businessCertificateNumber": "",
"channel": "",
"channelUserId": "",
"ownerFullName": "",
"ownerIdNumber": "",
"ownerIdType": "",
"ownerBirthDay": "",
"kinFullName": "",
"kinCountryCode": "",
"kinMobile": "",
"kinRelationship": "",
"onboardingMediaInfos": [
{
"fileUrl": "",
"mediaType": "",
"contentType": "",
"fileTypeId": "",
"fileKey": "",
"fileId": "",
}
],
"status": "",
"rejectReasonIds": [
],
"rejectReasonMsgs": [
],
"createTime": "",
"auditTime": "",
"businessIndustry": "",
"specifyIndustry": "",
"businessAddress": "",
}Query Onboarding Info - LLC
POST /onboarding/business/getCompanyOnboardingInfo
<Use this endpoint to query the onboarding information & materials for LLC type of SME>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
Response
{
"onboardingRequestId": "00000",
"smeName": "",
"businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO
"countryCode": "",
"mobile": "",
"email": "",
"krapin": "",
"businessCertificateNumber": "",
"channel": "",
"channelUserId": "",
"onboardingMediaInfos": [
{
"fileUrl": "",
"mediaType": "",
"contentType": "",
"fileTypeId": "",
"fileKey": "",
"fileId": "",
}
],
"shareholdersMemberInfos": [
{
"memberId": "",
"countryCode": "",
"mobile": "",
"idType": "",
"idNumber": "",
"firstName": "",
"middleName": "",
"lastName": "",
"fullName": "",
"kraPin": "",
"idFrontFileUrl": "",
"idFrontFileType": "",
"selfieFileUrl": "",
"selfieFileType": "",
"idBackFileUrl": "",
"idBackFileType": "",
"kraPinFileUrl": "",
"kraPinFileType": "",
}
],
"shareholdersCompanyInfos": [
{
"companyId": "",
"companyName": "",
"registrationFileKey": "",
"registrationFileUrl": "",
"registrationFileType": "",
}
],
"status": "",
"rejectReasonIds": [
],
"rejectReasonMsgs": [
],
"createTime": "",
"auditTime": "",
"businessIndustry": "",
"specifyIndustry": "",
"businessAddress": "",
}Query Onboarding Info - NGO / CBO
POST /onboarding/business/getOrganisationOnboardingInfo
<Use this endpoint to query the onboarding information & materials for NGO/CBO type of SME>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
Response
{
"onboardingRequestId": "00000",
"smeName": "",
"businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO
"countryCode": "",
"mobile": "",
"email": "",
"krapin": "",
"businessCertificateNumber": "",
"channel": "",
"channelUserId": "",
"onboardingMediaInfos": [
{
"fileUrl": "",
"mediaType": "",
"contentType": "",
"fileTypeId": "",
"fileKey": "",
"fileId": "",
}
],
"shareholdersMemberInfos": [
{
"memberId": "",
"countryCode": "",
"mobile": "",
"idType": "",
"idNumber": "",
"firstName": "",
"middleName": "",
"lastName": "",
"fullName": "",
"kraPin": "",
"idFrontFileUrl": "",
"idFrontFileType": "",
"selfieFileUrl": "",
"selfieFileType": "",
"idBackFileUrl": "",
"idBackFileType": "",
"kraPinFileUrl": "",
"kraPinFileType": "",
}
],
"shareholdersCompanyInfos": [
{
"companyId": "",
"companyName": "",
"registrationFileKey": "",
"registrationFileUrl": "",
"registrationFileType": "",
}
],
"status": "",
"rejectReasonIds": [
],
"rejectReasonMsgs": [
],
"createTime": "",
"auditTime": "",
"businessIndustry": "",
"specifyIndustry": "",
"businessAddress": "",
}Query Onboarding Info - Partnership
POST /onboarding/business/getPartnershipOnboardingInfo
<Use this endpoint to query the onboarding information & materials for LLC/NGO/CBO type of SME>
Parameters
onboardingRequestId
String
A unique string generated by Choice to identify a certain onboarding request
TRUE
Response
{
"onboardingRequestId": "00000",
"smeName": "",
"businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO
"countryCode": "",
"mobile": "",
"email": "",
"krapin": "",
"businessCertificateNumber": "",
"channel": "",
"channelUserId": "",
"onboardingMediaInfos": [
{
"fileUrl": "",
"mediaType": "",
"contentType": "",
"fileTypeId": "",
"fileKey": "",
"fileId": "",
}
],
"shareholdersMemberInfos": [
{
"memberId": "",
"countryCode": "",
"mobile": "",
"idType": "",
"idNumber": "",
"firstName": "",
"middleName": "",
"lastName": "",
"fullName": "",
"kraPin": "",
"idFrontFileUrl": "",
"idFrontFileType": "",
"selfieFileUrl": "",
"selfieFileType": "",
"idBackFileUrl": "",
"idBackFileType": "",
"kraPinFileUrl": "",
"kraPinFileType": "",
}
],
"shareholdersCompanyInfos": [
{
"companyId": "",
"companyName": "",
"registrationFileKey": "",
"registrationFileUrl": "",
"registrationFileType": "",
}
],
"status": "",
"rejectReasonIds": [
],
"rejectReasonMsgs": [
],
"createTime": "",
"auditTime": "",
"businessIndustry": "",
"specifyIndustry": "",
"businessAddress": "",
}Query Onboarding Status
POST /onboarding/business/getBusinessOnboardingStatus
<Use this endpoint to query the onboarding status>
Parameters
onboardingRequestId
string
The unique onboarding request id that was returned from Choice system.
FALSE
businessCerNo
string
Company/Organisation's incorporation certificate number.
Either onboardingRequestId or businessCerNo is mandatory.
FALSE
Response
{
"onboardingRequestId": "ONBOARD2309LKSD90432",
"onboardingStatus": "Completed successfully",
"rejectionReasonIds": [
],
"rejectReasonMsgs": [
],
"accountId": "46013xxxxxxxxx",
"accountType": "",
"auditTime": "",
}Last updated