Hello Everyone, Please, find the release notes!

This document outlines upcoming changes to **Mbanq’s APIs**, which will take effect **from 15th March 2025**. These updates are in compliance with the **Sponsor Bank’s new guidelines** on client information sharing. As part of this mandate, specific parameters must be transmitted to the Sponsor Bank **on a daily basis**.

### 📅 Key Dates

* **15th March 2025** – Mandatory go-live date for all platforms
* **3rd March 2025** – Sandbox availability for testing

### 🚨 Affected APIs

The following APIs will be updated. For each, the corresponding API documentation link is provided:

| API Group                             | API Document Link                                                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **AUTH API**                          | [https://apidocs.cloud.mbanq.com/reference/requestaccesstoken](https://apidocs.cloud.mbanq.com/reference/requestaccesstoken)             |
| **Get Client Template API**           | [https://apidocs.cloud.mbanq.com/reference/getclienttemplate](https://apidocs.cloud.mbanq.com/reference/getclienttemplate)               |
| **Create Client API**                 | [https://apidocs.cloud.mbanq.com/reference/createclient](https://apidocs.cloud.mbanq.com/reference/createclient)                         |
| **Edit Client API**                   | [https://apidocs.cloud.mbanq.com/reference/updateclient](https://apidocs.cloud.mbanq.com/reference/updateclient)                         |
| **Get Client API**                    | [https://apidocs.cloud.mbanq.com/reference/getclientbyid](https://apidocs.cloud.mbanq.com/reference/getclientbyid)                       |
| **Create Client Document Record API** | [https://apidocs.cloud.mbanq.com/reference/createclientidentifier-1](https://apidocs.cloud.mbanq.com/reference/createclientidentifier-1) |
| **Edit Client Document Record API**   | [https://apidocs.cloud.mbanq.com/reference/editclientidentifier](https://apidocs.cloud.mbanq.com/reference/editclientidentifier)         |
| **List Client Document Record API**   | [https://apidocs.cloud.mbanq.com/reference/listclientidentifiers](https://apidocs.cloud.mbanq.com/reference/listclientidentifiers)       |

This document provides a comparison between the **existing payload** and the **updated payload**, clearly highlighting the changes made. The goal is to ensure clarity on how the **data structure has evolved** and what **modifications** have been implemented.

***

### 👥 Impact of API Usage on Clientele Base

#### 🆕 New Clients

The updated APIs will be used to onboard new customers to the platform, ensuring they are integrated using the most **current data structure and functionality**.

#### ♻️ Existing Clients

For customers **onboarded on and after 1st January 2025**, the platform will:

* Share an **XLS** or **JSON** file containing the relevant client data with the **Mbanq team**
* The Mbanq team will **manually update** the records in the system
* This ensures **legacy customer data aligns** with the new API structure

***

### 1. 🔐 AUTH API

* **Affected API Endpoint**: `/oauth/token`  
* **Method**: `POST`  
* **Type of Change**: Modification  
* **API Doc**: *Request Access Token*  
* **Note**: Passing headers in the AUTH API is **only necessary** if the user credentials are stored and managed on **Mbanq**.

#### 📝 Description of Change

The **IP address** and **device identifier** (such as **device ID** or **browser fingerprint**) of the devices (mobile or system) used by end customers must be **captured and sent** using this API **each time** the user logs in or authenticates.

<table>
  <thead>
    <tr>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>New Headers</td>
      <td>
        X-FORWARDED-FOR : 222.12.211.12 -- New<br />
        X-DEVICE-FINGERPRINT : 09BD47A5-9380-40E3-AFF8-592D5E433 -- New
      </td>
    </tr>
  </tbody>
</table>

#### Definitions

| Field                | Type   | Optional | Description                                                                                                                                                                                                                                                                                                             |
| -------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-FORWARDED-FOR      | string | required | The IP address refers to the numerical label assigned to the device used during the account opening process. It identifies the device's location on a network and is used for tracking and verifying the origin of the account activity.                                                                                |
| X-DEVICE-FINGERPRINT | string | required | A device ID/browser fingerprint is a unique identifier generated by analyzing various attributes of a user's browser and device configuration. The resulting fingerprint is a single, distinctive string that represents the combination of these attributes, allowing for the identification of the browser or device. |

***

### 2. Get Client Template

**Affected API Endpoint(s):** `/v1/clients/template`\
**Method:** `GET`\
**Type of Change:** Modification\
**API Doc:** *Create Client*

#### Description of Change

When adding a new client, their occupation or designation must be captured. The selection should be made from a predefined list of occupations/designations. If the provided occupation does not match any value in the predefined list, it should be categorized as **"Others"**.

<table>
  <thead>
    <tr>
      <th>Status Code</th>
      <th>Sample Response</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>200</td>
      <td>
        {
          "clientOccupationOptions": [ ---New
            {
              "id": 10013,
              "name": "Sales Executive",
              "position": 0,
              "description": "",
              "active": true,
              "mandatory": false,
              "systemDefined": false,
              "parentId": 0,
              "codeName": "Occupation",
              "isMasked": false
            },
            {
              "id": 10014,
              "name": "Marketing Executive",
              "position": 0,
              "description": "",
              "active": true,
              "mandatory": false,
              "systemDefined": false,
              "parentId": 0,
              "codeName": "Occupation",
              "isMasked": false
            },
            {
              "id": 10015,
              "name": "Professor",
              "position": 0,
              "description": "",
              "active": true,
              "mandatory": false,
              "systemDefined": false,
              "parentId": 0,
              "codeName": "Occupation",
              "isMasked": false
            },
            {
              "id": 10015,
              "name": "Driver",
              "position": 0,
              "description": "",
              "active": true,
              "mandatory": false,
              "systemDefined": false,
              "parentId": 0,
              "codeName": "Occupation",
              "isMasked": false
            },
            {
              "id": 10015,
              "name": "Others",
              "position": 0,
              "description": "",
              "active": true,
              "mandatory": false,
              "systemDefined": false,
              "parentId": 0,
              "codeName": "Occupation",
              "isMasked": false
            }
          ]
        }
      </td>
    </tr>
  </tbody>
</table>

### 3. Create Client API

**Affected API Endpoint:** `/v1/clients`\
**Method:** `POST`\
**Type of Change:** Modification\
**API Doc:** *Create Client*

#### Description of Change

The client’s occupation needs to be captured upon onboarding a new client. The IP address and device identifier (device ID or browser fingerprint) of the devices (mobile or system) used by end customers must be captured and sent using this API each time the end client is onboarding either via mobile app or browser.

<table>
  <thead>
    <tr>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>New Headers</td>
      <td>
        X-FORWARDED-FOR : 222.12.211.12 -- New<br />
        X-DEVICE-FINGERPRINT : 09BD47A5-9380-40E3-AFF8-592D5E433 -- New
      </td>
    </tr>
  </tbody>
</table>

#### Definitions

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>New Payload</td>
      <td>
        <pre>
        {
          "address": [],
          "familyMembers": [],
          "officeId": 3,
          "isStaff": true,
          "staffId": null,
          "legalFormId": 1,
          "firstname": "john",
          "lastname": "doe",
          "occupationId": 31, // NEW
          "active": false,
          "dateFormat": "dd MMMM yyyy",
          "activationDate": "18 February 2025",
          "submittedOnDate": "18 February 2025",
          "savingsProductId": null
        }
        </pre>
      </td>
    </tr>
  </tbody>
</table>

***

### 4. Edit Client API

**Affected API Endpoint:** `/v1/clients/{clientId}`\
**Method:** `PUT`\
**Type of Change:** Modification\
**API Doc:** *Update Client*

#### Description of Change

The client’s occupation needs to be captured upon editing/updating the personal information of a client if the occupation is changed.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>New Payload</td>
      <td>
        <pre>
        {
          "legalFormId": 1,
          "firstname": "john",
          "lastname": "doe",
          "occupationId": 31, -- New
          "emailAddress": "[[email protected]](mailto:[email protected])",
          "mobileCountryCode": "+1",
          "mobileNo": "9999888777",
          "dateOfBirth": "05 May 1993",
          "submittedOnDate": "29 January 2025",
          "activationDate": "29 January 2025",
          "isStaff": false,
          "isOptedForMLAStatus": false,
          "currentMLAStatus": "",
          "genderId": 634,
          "clientNonPersonDetails": {
            "incorpValidityTillDate": ""
          },
          "active": true,
          "locale": "en",
          "dateFormat": "dd MMMM yyyy"
        }
        </pre>
      </td>
    </tr>
  </tbody>
</table>

### Definitions for New Fields Above

| Field          | Type    | Optional | Description                                                                                                                                                                                     |
| -------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `occupationId` | integer | required | The occupation refers to the profession, job title, or primary field of work of the account holder. This information provides insight into the account holder's employment status and industry. |

### 5. Get Client API

**Affected API Endpoint:** `v1/clients`\
**Method:** `GET`\
**Type of Change:** Modification\
**API Doc:** *Get Client Details*

#### Description of Change

The client's occupation information will be included in the response along with other fields.

<table>
  <thead>
    <tr>
      <th>Status Code</th>
      <th>Sample Response</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>200</td>
      <td>
        <pre>
        "occupation": {
          "id": 10013,
          "name": "Sales Executive",
          "position": 0,
          "description": "",
          "active": true,
          "mandatory": false,
          "systemDefined": false,
          "parentId": 0,
          "codeName": "Occupation",
          "isMasked": false
        },
        </pre>
      </td>
    </tr>
  </tbody>
</table>

### 6. Create Client Document Record API

**Affected API Endpoint:** `/v1/clients/{clientId}/identifiers`\
**Method:** `POST`\
**Type of Change:** Modification\
**API Doc:** [Create Client Identifier](https://apidocs.cloud.mbanq.com/reference/createclientidentifier)

#### Description of Change

The `issuedDate` (client document issued date) must be recorded when adding a new client document record.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>New Payload</td>
      <td>
        <pre>
        {
          "locale": "en",
          "dateFormat": "dd MMMM yyyy",
          "documentTypeId": 646,
          "status": "ACTIVE",
          "documentKey": "34543543",
          "description": "  43534543",
          "expiryDate": "18 February 2025",
          "issuedBy": "US Gov",
          "issuedDate": "8 February 2020" -- New
        }
        </pre>
      </td>
    </tr>
  </tbody>
</table>

***

### 7. Edit Client Document Record API

**Affected API Endpoint:** `/v1/clients/{clientId}/identifiers/{identifierId}`\
**Method:** `PUT`\
**Type of Change:** Modification\
**API Doc:** *Edit Client Document Record*

#### Description of Change

The `issuedDate` (client document issued date) must be recorded when updating a client document record.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>New Payload</td>
      <td>
        <pre>
        {
          "locale": "en",
          "dateFormat": "dd MMMM yyyy",
          "documentTypeId": 646,
          "status": "ACTIVE",
          "documentKey": "34543543",
          "description": "  43534543",
          "expiryDate": "18 February 2025",
          "issuedBy": "US Gov",
          "issuedDate": "8 February 2020" -- New
        }
        </pre>
      </td>
    </tr>
  </tbody>
</table>

#### Definitions for New Fields Above

| Field        | Type   | Optional | Description                                                                                                                                                                                                                             |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issuedDate` | string | required | Represents the date when a document or identifier was issued. This date is critical for tracking the validity period of certain documents, such as passports and licenses, and can also be used to ensure that documents are up to date |

### 8. List Client Document Records API

**Affected API Endpoint:** `v1/clients/{clientId}/identifiers`\
**Method:** `GET`\
**Type of Change:** Modification\
**API Doc:** *List Client Document Records*

#### Description of Change

The `issuedDate` of the client identifier will be included in the response along with other fields.

<table>
  <thead>
    <tr>
      <th>Status Code</th>
      <th>Sample Response</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>200</td>
      <td>
        <pre>
        "issuedDate": "2025-03-03 02:05:13" -- New
        </pre>
      </td>
    </tr>
  </tbody>
</table>

### Migration Plan

* The API changes will be available in the Stage environment starting March 4, 2025, and will become mandatory in production from March 15, 2025.
* For existing clients onboarded on the Mbanq platform on or after January 1, 2025, fintech partners are requested to submit the XLS file following the example provided below

***

## June 2024

**June 2024** - We have updated our API Guides to make them more comprehensive both technically and from a business user's perspective. In many places we have added business process descriptions that provide explanations for financial service processes. These updated guides should aid you in getting your Mbanq integration up and running more quickly.