# Onboarding

## Create a new client

<mark style="color:green;">`POST`</mark> `/onboarding/submitOnboardingRequest`

\<Use this endpoint to onboard a new client and submit its kyc information>

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>userId</code></td><td>string</td><td>A unique string to identify the user in the partner system. </td><td>TRUE</td></tr><tr><td><code>firstName</code></td><td>string</td><td>First name of the onboarding customer</td><td>TRUE</td></tr><tr><td><code>middleName</code></td><td>string</td><td>middle name of the onboarding customer</td><td>FALSE</td></tr><tr><td><code>lastName</code></td><td>string</td><td>last name of the onboarding customer</td><td>TRUE</td></tr><tr><td><code>birthday</code></td><td>string</td><td>Date of Birth; yyyy-MM-dd</td><td>TRUE</td></tr><tr><td><code>address</code></td><td>string</td><td>Physical address of the onboarding customer</td><td>TRUE</td></tr><tr><td><code>gender</code></td><td>integer</td><td><p>0 - Female</p><p>1 - Male</p></td><td>TRUE</td></tr><tr><td><code>countryCode</code></td><td>string</td><td>The country code of the mobile, that the customer is using to onboard</td><td>TRUE</td></tr><tr><td><code>mobile</code></td><td>string</td><td>The mobile number that the customer is using to onboard</td><td>TRUE</td></tr><tr><td><code>email</code></td><td>string</td><td>Email address of the customer</td><td>FALSE</td></tr><tr><td><code>idType</code></td><td>string</td><td><p>Type of the document that the customer is using to onboard.</p><p>101 - (Kenya) National ID</p><p>102 - (Kenya) Alien ID</p><p>103 - Passport</p></td><td>TRUE</td></tr><tr><td><code>idNumber</code></td><td>string</td><td>ID Number of National ID/Passport/Alien ID</td><td>TRUE</td></tr><tr><td><code>kraPin</code></td><td>string</td><td>KRA PIN / Tax Number</td><td>TRUE</td></tr><tr><td><code>employmentStatus</code></td><td>string</td><td><p>Customer's work status.</p><p>A - Employee</p><p>B - Self employed</p><p>C - Unemployed</p><p>D - Employer</p><p>E - Student</p><p>F - Others</p></td><td>TRUE</td></tr><tr><td><code>monthlyIncome</code></td><td>string</td><td><p>Customer monthly income information.</p><p>A - Less than Ksh. 14,999</p><p>B - Ksh. 15,000-24,999</p><p>C - Ksh. 25,000-39,999</p><p>D - Ksh. 40,000-59,999</p><p>E - Ksh. 60,000-84,999</p><p>F - Above Ksh. 85,000</p></td><td>TRUE</td></tr><tr><td><code>businessIndustry</code></td><td>string</td><td><p>This field captures the industry the business is operating in. Please submit the number representing the business sector.</p><p>1 - Agriculture and Agribusiness</p><p>2 - Manufacturing and Processing</p><p>3 - Construction and Engineering</p><p>4 - Retail and Wholesale Trade</p><p>5 - Information and Communication Technology</p><p>6 - Tourism and Hospitality</p><p>7 - Health and Wellness Services</p><p>8 - Education and Training</p><p>9 - Financial Services</p><p>10 - Professional Services</p><p>11 - Creative Industries</p><p>12 - Renewable Energy and Environmental Conservation</p><p>13 - Transport and Logistics</p><p>14 - Food and Beverage</p><p>15 - Textiles and Apparel</p><p>16 - Automotive and Engineering Services</p><p>17 - Beauty and Personal Care</p><p>18 - Real Estate and Property Development</p><p>19 - Consulting and Business Services</p><p>20 - Social Enterprises and NGOs</p><p>21 - Others, please specify</p></td><td>FALSE</td></tr><tr><td><code>specifyIndustry</code></td><td>string</td><td>When businessIndustry == Others, please specify, this field is Mandatory.</td><td>FALSE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
  "onboardingRequestId": "ONBOARD7695534567876"
}
```

{% endtab %}

{% tab title="Others" %}

```json
{
  "code": "12005",
  "msg": "Invalid signature"
}
```

{% endtab %}
{% endtabs %}

## Upload client KYC document

<mark style="color:green;">`POST`</mark> `/onboarding/uploadMedia`

\<Use this endpoint to submit onboarding client's media file, like its ID documents, selfie document>

**Parameters**

<table data-full-width="false"><thead><tr><th width="243">Parameters</th><th width="85">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>onboardingRequestId</code></td><td>string</td><td>The unique onboarding request id that was returned from Choice system.</td><td>TRUE</td></tr><tr><td><code>mediaType</code></td><td>string</td><td>This is to specify the document type. Please refer to <a href="..#documents">Documents</a></td><td>TRUE</td></tr><tr><td><code>mediaBase64</code></td><td>integer</td><td>BASE64 text of the document file</td><td>TRUE</td></tr><tr><td><code>contentType</code></td><td>string</td><td>pdf/image</td><td>FALSE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

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

{% endtab %}

{% tab title="Others" %}

```json
{
 "code": "12005",
 "msg": "Invalid signature"
}
```

{% endtab %}
{% endtabs %}

## Query onboarding status

<mark style="color:green;">`POST`</mark> `/onboarding/getOnboardingStatus`

\<Use this endpoint to query the onboarding status>

**Parameters**

<table data-full-width="false"><thead><tr><th width="243">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>userId</code></td><td>string</td><td>The unique string to identify the user in the partner system. </td><td>FALSE</td></tr><tr><td><code>onboardingRequestId</code></td><td>string</td><td>The unique onboarding request id that was returned from Choice system.</td><td>FALSE</td></tr><tr><td><code>mobile</code></td><td>string</td><td><p>The mobile number that the customer is using to onboard.</p><p>Use either one from userId / onboardingRequestId / mobile to query the onboarding status.</p></td><td>FALSE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

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

{% endtab %}

{% tab title="Others" %}

```json
{
 "code": "12005",
 "msg": "Invalid signature"
}
```

{% endtab %}
{% endtabs %}

## Query client KYC information

<mark style="color:green;">`POST`</mark> `/onboarding/getUserKyc`

\<Use this endpoint to get the KYC information and its status>

**Parameters**

<table data-full-width="false"><thead><tr><th width="243">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>onboardingRequestId</code></td><td>string</td><td>The unique onboarding request id that was returned from Choice system.</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

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

{% endtab %}

{% tab title="Others" %}

```json
{
 "code": "12005",
 "msg": "Invalid signature"
}
```

{% endtab %}
{% endtabs %}

## Query client KYC media information

<mark style="color:green;">`POST`</mark> `/onboarding/personal/getKycMediaList`

\<Use this endpoint to get client's kyc media information>

**Parameters**

<table data-full-width="false"><thead><tr><th width="243">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>onboardingRequestId</code></td><td>string</td><td>The unique onboarding request id that was returned from Choice system.</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

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

{% endtab %}

{% tab title="Others" %}

```json
{
 "code": "12005",
 "msg": "Invalid signature"
}
```

{% endtab %}
{% endtabs %}

## Query client onboarding request ID

<mark style="color:green;">`POST`</mark> `/onboarding/getOnboardingRequestId`

\<This endpoint allows you to get client's onboardingRequestId using its user ID or mobile number>

**Parameters**

<table data-full-width="false"><thead><tr><th width="243">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>userId</code></td><td>string</td><td>The unique string to identify the user in the partner system. </td><td>FALSE</td></tr><tr><td><code>mobile</code></td><td>string</td><td>User's mobile number / The mobile number that the user used to onboard</td><td>FALSE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
  "onboardingRequestId": ""
}
```

{% endtab %}

{% tab title="Others" %}

```json
{
 "code": "12005",
 "msg": "Invalid signature"
}
```

{% endtab %}
{% endtabs %}
