# Account Management

## Query Account Details

<mark style="color:green;">`POST`</mark> `/query/getAccountDetails`

Use this endpoint to get specifica details of any particular API-onboarded account.&#x20;

<table data-full-width="false"><thead><tr><th width="219">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>Account number being queried</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "accountId": "", //string
  "accountName": "", //string
  "currency": "", //string
  "accountType": "", //refer to account type definition
  "shortCode": "", //account short code, 
  "accountStatus": "", //int, 0 - Normal; 1 - Locked; 2 - Closed
  "createTime": "", //unix timestamp of account creation time
  "balance": "", //2 dp, eg 12.3 returns "12.30", 453 returns "453.00"
  "dormantStatus": "", //0-Normal; 1-Dormant
  "freezeStatus": "", //0-Normal; 1-Frozen
}
```

{% endtab %}
{% endtabs %}

## Get All Accounts of a Client

<mark style="color:green;">`POST`</mark> `/account/queryAccountListByUserId`

Use this endpoint to get a list of all API-onboarded accounts tied to a particular User ID.

<table data-full-width="false"><thead><tr><th width="145.40008544921875">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>userId</code></td><td>string</td><td>Unique string you assigned to identify the user(s)</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "accounts": [
    {
      "accountId": "",
      "accountName": "",
      "currency": "",
      "accountType": "", 
                      //C001-Current Account
                      //C002-Wallet Account
                      //C004-Loan Account
                      //C006-Fixed Deposit Account
                      //B001-SME Account
                      //B005-Business Loan Account
                      //B006-Business Fixed Deposit Account
      "dormantStatus": "", //0-Normal; 1-Dormant;
      "freezeStatus": "", //0-Normal; 1-Frozen;
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get Abnormal Account List

<mark style="color:green;">`POST`</mark> `/query/getAbnormalAccountList`

Use this endpoint to get a list of all accounts with abnormal status (i.e., either dormant or frozen) under your BaaS channel.&#x20;

<table data-full-width="false"><thead><tr><th width="127.2667236328125">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>pageNo</code></td><td>int</td><td>Page number</td><td>TRUE</td></tr><tr><td><code>pageSize</code></td><td>int</td><td>Page size</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "total": "",
  "resultArray": [
    {
      "userId": "",
      "accountId": "",
      "accountType": "",
      "status": [
        {1},
        {2},
        //Abnormal status; 1-Dormant; 2-Restricted; 3-Frozen
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Apply for `shortCode`

<mark style="color:green;">`POST`</mark> `/account/applyForShortCode`

Use this endpoint to apply for a `shortCode` (much shorter account number tied to your `accountId`) for any given account under your BaaS channel.&#x20;

<table data-full-width="false"><thead><tr><th width="141.13336181640625">Parameters</th><th width="103.2666015625">Type</th><th width="307">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>Account for which a short code is being applied </td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "accountId": "", 
  "shortCode": "", //generated shortcode
}
```

{% endtab %}
{% endtabs %}

### Query `shortCode` By `AccountId`

<mark style="color:green;">`POST`</mark> `/account/queryForShortCode`

Use this endpoint to query get a particular account's assigned `shortCode` .

<table data-full-width="false"><thead><tr><th width="174.2000732421875">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>Account for which a short code is being queried</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "accountId": "", 
  "shortCode": "",
}
```

{% endtab %}
{% endtabs %}

### Query `accountId` By `shortCode`

<mark style="color:green;">`POST`</mark> `/account/queryAccountByShortCode`

Use this endpoint to return the full official account number tied to an assigned `shortCode` .

<table data-full-width="false"><thead><tr><th width="219">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>shortCode</code></td><td>string</td><td>The short code of the account that the end user wants to query its account number.</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "accountId": "", 
  "shortCode": "", 
}
```

{% endtab %}
{% endtabs %}

## Activate Dormant Account

<mark style="color:green;">`POST`</mark> `/account/activateAccount`

Use this endpoint to activate any dormant account under your BaaS channel.&#x20;

{% hint style="info" %}
NOTE: An account with no transactions for 6 consecutive months will automatically be marked as **dormant**.
{% endhint %}

<table data-full-width="false"><thead><tr><th width="219">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>The number of the dormant account that the user wants to activate.</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "accountId": "", 
  "shortCode": "", 
}
```

{% endtab %}
{% endtabs %}

## Edit SME Sub-Account/VA Name

<mark style="color:green;">`POST`</mark> `/account/editSubAccountName`

Use this endpoint to edit the name assigned to a virtual or sub-account to help SMEs manage and distinguish between multiple virtual accounts more efficiently.&#x20;

By default, sub-account/VA name takes the same name as the parent SME.&#x20;

To customise it, pass in `subAccountName` a identifier string specific to the particular sub-account/VA and this will be appended to the Business Name delimited by an underscore (i.e., \_). If no value is passed, the sub-account name will be reset to match the parent SME's `businessName`. \\

\
**Example**: Take a parent SME with `businessName`: Choice Microfinance Bank\
and `subAccountName`: ABC Company
\
\
Final sub-account/VA name: **Choice Microfinance Bank\_ABC Company**

{% hint style="info" %}
**NOTE:** The **Business Name** is always used as a fixed prefix in the final account name.
{% endhint %}

<table data-full-width="false"><thead><tr><th width="157.000244140625">Parameters</th><th width="84.0665283203125">Type</th><th width="399.8001708984375">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>Account number. Must belong to the SME customer. </td><td>TRUE</td></tr><tr><td><code>subAccountName</code></td><td>string</td><td>Sub-account identifier suffix to be appended to the parent-SME name, delimited by an underscore (_)<br><br>Final account name &#x3C;= 255 characters</td><td>FALSE</td></tr></tbody></table>

**Response**

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

```json
{
  "applicationId": "",
}
```

{% endtab %}
{% endtabs %}

## Cancel Account Operation

<mark style="color:green;">`POST`</mark>`/account/cancelAccountOperation`

This endpoint is used to cancel account operation requests that have not been confirmed by OTP, which include:\
`/account/activateAccount`\
`/user/verifyEmailAddress`\
`/user/addEmail`

<table><thead><tr><th width="151.2000732421875">Fields</th><th width="108.800048828125">Type</th><th width="312.5999755859375">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>requestId</code></td><td>string</td><td>Request or application to be cancelled </td><td>TRUE</td></tr></tbody></table>

**Response**

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

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://choice-bank.gitbook.io/choice-bank/account/account-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.