# Contacts (Beneficiaries)

Manage the user's saved beneficiary list. All endpoints use WebView session auth — see [README](README.md).

```
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary?dashurl=1
```

---

## List Categories

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

Empty POST body.

### Response

```json
{
  "success": true,
  "data": [
    { "id": "100001", "categoryName": "Myself",   "numBenef": "2" },
    { "id": "100002", "categoryName": "Friends",  "numBenef": "10" },
    { "id": "100003", "categoryName": "Business", "numBenef": "8" },
    { "id": "100004", "categoryName": "Family",   "numBenef": "5" }
  ]
}
```

| Field | Description |
|---|---|
| `id` | Category ID — use as `searchCategoryId` when filtering contacts |
| `categoryName` | Display name |
| `numBenef` | Number of beneficiaries in this category (string) |

---

## List Contacts

```
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) |
| `benefType` | `A` | `A`=All, `L`=Local, `I`=Internal, `S`=Swift |
| `sortBenef` | `name` | Sort field |
| `sortDir` | `asc` | Sort direction |
| `start` | `1` | Start record index (1-based) |
| `end` | `100` | End record index |
| `includeCount` | `1` | Include `total_count` |

### Beneficiary Types

| `benefType` | Meaning |
|---|---|
| `I` | Internal (MIB to MIB) |
| `L` | Local (other Maldivian banks, e.g. BML) |
| `S` | Swift (international) |

### Response

```json
{
  "success": true,
  "total_count": "48",
  "data": [
    {
      "benefNo": "100001",
      "benefName": "Person Name",
      "benefNickName": "Nickname",
      "benefAccount": "7700000000001",
      "benefType": "L",
      "bankColor": "#AC0000",
      "benefBankName": "Bank of Maldives PLC",
      "bankCode": "BML",
      "benefSwiftCode": "MALBMVMV",
      "benefStatus": "A",
      "benefBankId": "3",
      "transferCy": "462",
      "transferCyDesc": "MVR",
      "customerImgHash": "abcd1234hash",
      "benefCategoryID": "100002"
    }
  ]
}
```

| Field | Description |
|---|---|
| `benefNo` | Unique beneficiary ID — use for delete |
| `benefNickName` | User-assigned nickname (prefer over `benefName` for display) |
| `benefType` | `L`, `I`, or `S` |
| `bankColor` | Hex color for placeholder avatar background |
| `customerImgHash` | Hash for fetching profile photo (`null` if no photo) |
| `benefCategoryID` | Category ID — `"0"` means uncategorized |
| `transferCyDesc` | Currency (e.g. `"MVR"`, `"USD"`) |

---

## Get Profile Image

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

Body: `imageHash=<customerImgHash>`

### Response

```json
{
  "success": true,
  "profileImage": "<base64-encoded JPEG>"
}
```

`profileImage` is raw base64 JPEG with no data URI prefix. Decode with `Base64.decode(value, Base64.DEFAULT)` then `BitmapFactory.decodeByteArray(...)`. Cache decoded bitmaps — the same hash may appear across multiple contacts.

---

## Create Contact

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

```
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary/createNew
```

### Request Body (form-urlencoded)

| Field | Description |
|---|---|
| `benefType` | `"I"` = MIB internal, `"L"` = local/BML |
| `benefAccount` | Beneficiary account number |
| `benefName` | Full name |
| `nickName` | Display nickname |
| `bankNo` | `2` = MIB, `3` = BML/local |
| `transferCy` | Currency numeric code (`"462"` = MVR) |
| `categoryId` | Category ID (`"0"` = uncategorized) |
| `imageSet` | `"1"` if image provided, `"0"` otherwise |
| `image` | Base64-encoded image (empty string if none) |
| `benefIban` | Leave blank |
| `benefAddress` | Leave blank |
| `benefCity` | Leave blank |
| `benefCountry` | `"4"` |
| `benefBankSwift` | Leave blank |
| `benefBankName` | Leave blank |
| `benefBankBranch` | Leave blank |
| `benefBankAddress` | Leave blank |
| `benefBankCity` | Leave blank |
| `benefBankCountry` | `"4"` |
| `intBankSwift` | Leave blank |
| `intBankName` | Leave blank |
| `intBankAddress` | Leave blank |
| `intBankBranch` | Leave blank |
| `intBankCity` | Leave blank |
| `intBankCountry` | `"4"` |
| `transferCySwift` | `"840"` (USD numeric — static) |
| `email` | Leave blank |
| `contactNumber` | Leave blank |
| `website` | Leave blank |

### Response

```json
{ "success": true }
```

`success: true` confirms the contact was saved.

---

## Delete Contact

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

Body: `benefNo=<benefNo>`

### Response

```json
{ "success": true }
```

---

## Contact Stats

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

Empty POST body.

### Response

```json
{
  "success": true,
  "data": [
    { "type": "L", "count": "30" },
    { "type": "I", "count": "10" },
    { "type": "S", "count": "2" }
  ]
}
```

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

---

&nbsp;

---

[← Transfer](08-transfer.md)