# Onboarding

## Create a new client

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

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

**Parameters**

<table data-full-width="false"><thead><tr><th width="189.55548095703125">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>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>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>address</code></td><td>string</td><td>Physical address of the onboarding customer</td><td>FALSE</td></tr><tr><td><code>kraPin</code></td><td>string</td><td>KRA PIN / Tax Number</td><td>FALSE</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>frontSidePhoto</code></td><td>string</td><td>Base 64 string</td><td>TRUE</td></tr><tr><td><code>selfiePhoto</code></td><td>string</td><td>Base 64 string</td><td>TRUE</td></tr></tbody></table>

**Response**

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

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

{% 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>

{% hint style="info" %}
NOTE: These 3 parameters should NOT be blank or null at the same time. At least provide one of them to query the onboarding status.
{% endhint %}

**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>

{% hint style="info" %}
NOTE: These parameters should NOT all be blank or null at the same time. At least provide one of them to query the onboarding status.
{% endhint %}

**Parameters**

<table data-full-width="false"><thead><tr><th width="193.7999267578125">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 %}
{% endtabs %}
