Onboard

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 current account

POST /onboarding/submitOnboardingRequest

Use this endpoint to initiate a new current account onboarding and submit KYC information.

Parameters	Type	Description	Required?
userId	string	Unique string what identifies the user in your 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	Country code of the customer's mobile	TRUE
mobile	string	End user's mobile number	TRUE
email	string	End users's email address	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	Mandatory when businessIndustry == Others	FALSE

Response

00000

{
  "onboardingRequestId": "ONBOARD7695534567876"
}

Others

Upload KYC media

POST /onboarding/uploadMedia

Use this endpoint to submit the required KYC documentation as media file, e.g., national ID, selfie, etc.

Parameters	Type	Description	Required?
onboardingRequestId	string	Unique onboarding request ID we returned	TRUE
mediaType	string	Document type	TRUE
mediaBase64	integer	BASE64 text of the document file	TRUE
contentType	string	pdf/image	FALSE

Response

00000

{
  "code": "00000",
  "msg": "Completed successfully"
}

Others

Query onboarding status

POST /onboarding/getOnboardingStatus

Once you have initiated the onboarding, you can call this endpoint at any point to query its status.

NOTE: You must pass a non-null value for at least one of these three parameters.

Parameters

Parameters	Type	Description	Required?
userId	string	Unique string what identifies the user in your system	FALSE
onboardingRequestId	string	Unique onboarding request ID we assigned	FALSE
mobile	string	Mobile number end-user used to onboard	FALSE

Response

00000

{
  "onboardingRequestId": "ONBOARD2309LKSD90432",
  "onboardingStatus": "Completed successfully"
}

Others

Query KYC information

POST /onboarding/getUserKyc

Use this endpoint to get the KYC information/details you submitted as well the onboarding status.

Parameters

Parameters	Type	Description	Is Required
onboardingRequestId	string	Unique onboarding request ID we assigned	TRUE

Response

00000

{
  "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
  
}

Others

Query KYC media

POST /onboarding/personal/getKycMediaList

Use this endpoint to get a list of the KYC media files you uploaded.

Parameters

Parameters	Type	Description	Is Required
onboardingRequestId	string	Unique onboarding request ID we assigned	TRUE

Response

00000

{
    "mediaList": [
        {    
            "mediaType": "",
            "fileTypeId": "",
            "mediaUrl": "",
        }, {}    
    ]
}

Others

Query onboarding request ID

POST /onboarding/getOnboardingRequestId

Use this endpoint to get the end-user's onboardingRequestId using either the userId (if unique) or mobile you passed.

Parameters

Parameters	Type	Description	Required?
userId	string	Unique string what identifies the user in your system	FALSE
mobile	string	Mobile number end-user used to onboard	FALSE

Response

00000

{
  "onboardingRequestId": ""
}

Others