# MIB Contacts (Beneficiary) API

The contacts/beneficiary system is served from the MIB WebView subdomain. All endpoints use
session-cookie authentication (same cookies as the financing WebView).

## Authentication

All requests use the same session cookies:

```
Cookie: mbmodel=IOS-1.0; xxid=<session_xxid>; IBSID=<session_xxid>; mbnonce=<nonceGenerator>; time-tracker=597
```

All AJAX POST requests also require:

```
X-Requested-With: XMLHttpRequest
Origin: https://faisamobilex-wv.mib.com.mv
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary?dashurl=1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
```

---

## Endpoints

### 1. Get Categories

**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getCategories`

No request body required (empty POST).

**Response:**

```json
{
  "success": true,
  "responseCode": "1",
  "reasonText": "Category retrieval success",
  "reasonCode": "105",
  "data": [
    {
      "id": "100001",
      "categoryName": "Myself",
      "icon": "f091",
      "createdDate": "2023-01-01 00:00:00",
      "modifiedDate": null,
      "numBenef": "2"
    },
    {
      "id": "100002",
      "categoryName": "Friends",
      "icon": "f095",
      "createdDate": "2023-01-01 00:00:00",
      "modifiedDate": "2023-01-02 00:00:00",
      "numBenef": "10"
    },
    {
      "id": "100003",
      "categoryName": "Business",
      "icon": "f097",
      "createdDate": "2023-01-01 00:00:00",
      "modifiedDate": "2023-01-02 00:00:00",
      "numBenef": "8"
    },
    {
      "id": "100004",
      "categoryName": "Family",
      "icon": "f090",
      "createdDate": "2023-01-01 00:00:00",
      "modifiedDate": "2023-01-02 00:00:00",
      "numBenef": "5"
    }
  ]
}
```

Fields:
- `id` — category ID (used as `searchCategoryId` when filtering contacts)
- `categoryName` — display name
- `icon` — font-awesome icon code (used in web UI, ignore in native app)
- `numBenef` — number of beneficiaries in this category (string)

---

### 2. Get Contacts (Paginated)

**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/main`

**Request body (form-urlencoded):**

| Field              | Example  | Description                                               |
|--------------------|----------|-----------------------------------------------------------|
| `page`             | `1`      | Page number (1-based)                                     |
| `search`           | ``       | Search query (empty = all)                                |
| `searchCategoryId` | `0`      | Category filter (`0` = all categories)                    |
| `benefType`        | `A`      | Beneficiary type: `A`=All, `L`=Local, `I`=Internal, `S`=Swift |
| `sortBenef`        | `name`   | Sort field                                                |
| `sortDir`          | `asc`    | Sort direction                                            |
| `start`            | `1`      | Record start index (1-based)                              |
| `end`              | `100`    | Record end index                                          |
| `includeCount`     | `1`      | Include `total_count` in response                         |

**Beneficiary types:**
- `L` — Local (other Maldivian banks, e.g. BML)
- `I` — Internal (MIB to MIB transfers)
- `S` — Swift (international transfers)

**Response:**

```json
{
  "success": true,
  "responseCode": "1",
  "reasonText": "beneficiary retrieval success",
  "reasonCode": "103",
  "data": [
    {
      "benefNo": "100001",
      "benefName": "Person Name",
      "benefNickName": "Nickname",
      "benefAccount": "7700000000001",
      "benefType": "L",
      "bankColor": "#AC0000",
      "benefBankName": "Bank of Maldives PLC",
      "bankCode": "BML",
      "benefBankBranch": null,
      "benefAddress1": null,
      "benefAddress2": null,
      "benefAddress3": null,
      "benefCity": null,
      "benefRegion": null,
      "benefCountry": null,
      "benefStatus": "A",
      "benefBankId": "3",
      "benefSwiftCode": "MALBMVMV",
      "transferCy": "462",
      "transferCyDesc": "MVR",
      "bicCode": null,
      "intermBankCode": "0",
      "customerImgHash": "abcd1234hash...",
      "benefImgHash": "abcd1234hash...",
      "benefCategoryID": "100002",
      "BENEF_CIF_NO": null,
      "rnum": "1",
      "last": "0"
    },
    {
      "benefNo": "100002",
      "benefName": "Another Person",
      "benefNickName": "MIB Contact",
      "benefAccount": "90103100000001000",
      "benefType": "I",
      "bankColor": "#FE860E",
      "benefBankName": "MIB",
      "bankCode": "MIB",
      "benefBankBranch": null,
      "benefStatus": "A",
      "benefBankId": "2",
      "benefSwiftCode": "SWIFTCODE",
      "transferCy": "462",
      "transferCyDesc": "MVR",
      "customerImgHash": null,
      "benefImgHash": null,
      "benefCategoryID": "0",
      "rnum": "2",
      "last": "1"
    }
  ],
  "total_count": "48",
  "pos": "1"
}
```

Key fields:
- `benefNo` — unique beneficiary ID
- `benefNickName` — user-assigned nickname (prefer over `benefName` for display)
- `benefType` — `L`, `I`, or `S`
- `bankColor` — hex color representing the bank (use for placeholder avatar background)
- `customerImgHash` — hash used to fetch profile photo (null if no photo set)
- `benefCategoryID` — category ID, `"0"` means uncategorized
- `transferCyDesc` — currency (MVR, USD)
- `rnum` — row number (1-based position in full sorted list)
- `last` — `"1"` if this is the last record on the page

Pagination: use `start`/`end` to page through results. `total_count` gives the total number of records.

---

### 3. Get Profile Image

**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getProfileImage`

**Request body (form-urlencoded):**

| Field       | Description                        |
|-------------|------------------------------------|
| `imageHash` | The `customerImgHash` from contact |

**Response:**

```json
{
  "success": true,
  "responseCode": "1",
  "reasonCode": "1",
  "reasonText": "image found",
  "profileImage": "<base64-encoded JPEG>"
}
```

- `profileImage` — raw base64-encoded JPEG (no data URI prefix)
- Decode with `Base64.decode(value, Base64.DEFAULT)` then `BitmapFactory.decodeByteArray(...)`
- The same hash may be reused across multiple contacts (deduplication recommended)

---

### 4. Get Stats (optional)

**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getStats`

No request body required.

**Response:**

```json
{
  "success": true,
  "responseCode": "1",
  "reasonText": "Beneficiary Stats Retrieved",
  "reasonCode": "109",
  "data": [
    { "type": "L", "count": "30" },
    { "type": "I", "count": "10" },
    { "type": "S", "count": "2" }
  ]
}
```

Gives counts per beneficiary type. Useful for showing tab badges.

---

## Notes

- Profile images are fetched on-demand per contact. Cache decoded bitmaps in memory to avoid re-fetching.
- Contacts with `customerImgHash == null` have no profile photo; show initials + bank color as placeholder.
- The `benefCategoryID` of `"0"` means uncategorized (not in any category group).
- Pagination: use `start=1&end=100` for the first 100 records. Increment accordingly using `total_count`.