> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Holders

> KYC cardholder creation, update, approval tracking, and listing

# Card Holder APIs

Manage KYC-verified cardholders. Required when card type has `needCardHolder=true`. Supports B2B (simplified) and B2C (full KYC with ID documents) models.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/card/holder/...`
</Info>

<Warning>
  The `cardHolderModel` values `B2B` and `B2C` are **internal codes** — they do NOT correspond to company vs individual. Check the `metadata.cardHolderModel` field from the [Card Types](/baas/api/reference/fincard-virtual/cards) response.
</Warning>

***

## Cardholder Occupations

List available occupation codes for B2C cardholder creation.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/holder/occupations
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field            | Type   | Description                                      |
| ---------------- | ------ | ------------------------------------------------ |
| `occupationCode` | String | Occupation code (e.g. `11-1011`)                 |
| `description`    | String | Occupation description (e.g. `Chief Executives`) |

***

## Create Cardholder V2

Create a new KYC-verified cardholder. Fields differ based on `cardHolderModel`.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/holder/v2/create
```

### B2B Model Request

| Field             | Type   | Required | Description                                                                           |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `cardHolderModel` | String | Yes      | `B2B`                                                                                 |
| `merchantOrderNo` | String | Yes      | Client tx ID `[20..40]`                                                               |
| `cardTypeId`      | Long   | Yes      | Card type ID                                                                          |
| `areaCode`        | String | Yes      | Mobile area code `[2..5]` (from `supportHolderAreaCode`)                              |
| `mobile`          | String | Yes      | Mobile number `[5..20]`                                                               |
| `email`           | String | Yes      | Email `[5..50]` (receives verification codes)                                         |
| `firstName`       | String | Yes      | First name (English only) `[2..32]`                                                   |
| `lastName`        | String | Yes      | Last name (English only) `[2..32]`                                                    |
| `birthday`        | String | Yes      | Date of birth `yyyy-MM-dd`                                                            |
| `country`         | String | Yes      | Bill address country (ISO alpha-2, from `supportHolderRegin`)                         |
| `town`            | String | Yes      | Bill address city code (from [City List](/baas/api/reference/fincard-virtual/common)) |
| `address`         | String | Yes      | Bill address `[2..40]` (letters, numbers, hyphens, spaces)                            |
| `postCode`        | String | Yes      | Postal code `[2..15]`                                                                 |

<Note>
  Total length of `firstName` + `lastName` cannot exceed 32 characters (including spaces).
</Note>

### B2C Model Request (additional fields)

All B2B fields plus:

| Field                   | Type   | Required | Description                                                                          |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `nationality`           | String | Yes      | ISO alpha-2 (from `supportHolderRegin`)                                              |
| `gender`                | String | Yes      | `M` (male) / `F` (female)                                                            |
| `occupation`            | String | Yes      | Occupation code (from [Occupations](#cardholder-occupations))                        |
| `annualSalary`          | String | Yes      | e.g. `100000 USD`                                                                    |
| `accountPurpose`        | String | Yes      | English only (e.g. `Living Expense`)                                                 |
| `expectedMonthlyVolume` | String | Yes      | e.g. `10000 USD`                                                                     |
| `idType`                | String | Yes      | `PASSPORT` / `HK_HKID` / `DLN` / `GOVERNMENT_ISSUED_ID_CARD`                         |
| `idNumber`              | String | Yes      | ID number `[2..50]`                                                                  |
| `issueDate`             | String | Yes      | ID issue date `yyyy-MM-dd`                                                           |
| `idNoExpiryDate`        | String | Yes      | ID expiry date `yyyy-MM-dd`                                                          |
| `idFrontId`             | String | Yes      | Front photo file ID (from [Upload File](/baas/api/reference/fincard-virtual/common)) |
| `idBackId`              | String | Yes      | Back photo file ID                                                                   |
| `idHoldId`              | String | Yes      | Selfie photo file ID                                                                 |
| `ipAddress`             | String | Yes      | IPv4 address                                                                         |

### ID Types by Region

| Region        | Supported ID Types                             |
| ------------- | ---------------------------------------------- |
| **Hong Kong** | `PASSPORT`, `HK_HKID`                          |
| **All other** | `PASSPORT`, `DLN`, `GOVERNMENT_ISSUED_ID_CARD` |

### Restricted Countries/Regions

Cuba, North Korea, Egypt, Iran, Myanmar, Nigeria, Russia, Belarus, South Africa, Syria, Ukraine, Venezuela, Sudan, South Sudan, Libya, Crimea, Burundi, Central African Republic, Somalia, Zimbabwe, Afghanistan.

### Response `data`

| Field                | Type   | Description                                             |
| -------------------- | ------ | ------------------------------------------------------- |
| `holderId`           | Long   | **Cardholder ID** (use in create card)                  |
| `merchantOrderNo`    | String | Client tx ID                                            |
| `cardTypeId`         | Long   | Card type ID                                            |
| `statusFlowLocation` | String | `admin` (platform review) / `channel` (bank review)     |
| `status`             | String | `wait_audit` / `pass_audit` / `under_review` / `reject` |
| `description`        | String | Status description                                      |

<Note>
  Approval flow: **admin** review first → then **channel** (bank) review. Cardholder can only be used for card creation when `status=pass_audit`.
</Note>

***

## Update Cardholder V2

Update a rejected cardholder. Only allowed when `statusFlowLocation=admin` AND `status=reject`.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/holder/v2/update
```

**Request:** Same fields as Create + `holderId` (required). All fields are re-submitted.

**Response:** Same as Create response.

<Warning>
  Cardholder information **cannot be modified after bank submission**. Email and ID number are **globally unique** per card type — duplicates are rejected.
</Warning>

***

## Cardholder List

Query cardholders with pagination and filters.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/holder/list
```

**Request:**

| Field             | Type    | Required | Description                                 |
| ----------------- | ------- | -------- | ------------------------------------------- |
| `pageNum`         | Integer | Yes      | Page number (default 1)                     |
| `pageSize`        | Integer | Yes      | Page size (max 100, default 10)             |
| `holderId`        | Long    | No       | Filter by holder ID                         |
| `areaCode`        | String  | No       | Filter by area code (requires `mobile` too) |
| `mobile`          | String  | No       | Filter by mobile                            |
| `email`           | String  | No       | Filter by email                             |
| `merchantOrderNo` | String  | No       | Filter by client tx ID                      |

**Response `data`:** `{ total, records[] }`

| Field                | Type   | Description                                             |
| -------------------- | ------ | ------------------------------------------------------- |
| `holderId`           | String | Cardholder ID                                           |
| `merchantOrderNo`    | String | Client tx ID                                            |
| `cardTypeId`         | String | Card type ID                                            |
| `areaCode`           | String | Mobile area code                                        |
| `mobile`             | String | Mobile number                                           |
| `email`              | String | Email                                                   |
| `firstName`          | String | First name                                              |
| `lastName`           | String | Last name                                               |
| `birthday`           | String | Date of birth                                           |
| `country`            | String | Country                                                 |
| `town`               | String | City code                                               |
| `address`            | String | Address                                                 |
| `postCode`           | String | Postal code                                             |
| `statusFlowLocation` | String | `admin` / `channel`                                     |
| `status`             | String | `wait_audit` / `pass_audit` / `under_review` / `reject` |
| `description`        | String | Status description                                      |
| `createTime`         | Long   | Creation time (ms)                                      |
| `updateTime`         | Long   | Update time (ms)                                        |

***

## Deprecated Endpoints

The following V1 endpoints are still available but deprecated:

| Endpoint  | Path                  | Replacement                  |
| --------- | --------------------- | ---------------------------- |
| Create V1 | `/card/holder/create` | Use `/card/holder/v2/create` |
| Update V1 | `/card/holder/update` | Use `/card/holder/v2/update` |