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

# Create and manage cardholders

> Register cardholder identities before issuing cards, and update cardholder details as needed.

A cardholder represents the person who will use a card. You must create a cardholder before issuing any card to them. Once a card is linked to a cardholder, the association cannot be changed.

<Info>
  **Prerequisites**

  * A UQPAY account with Card Issuance enabled
  * An API token from the [Access Token](/account-center/v1.6/api-reference/access-token) endpoint
</Info>

## Create a cardholder

Send a `POST` request to the [Create Cardholder](/card-issuance/v1.6/api-reference/create-cardholder) endpoint with the cardholder's identity information.

**Required fields:**

| Field          | Description                                                                                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name`   | Cardholder's first name (letters, spaces, and hyphens only)                                                                                                                       |
| `last_name`    | Cardholder's last name                                                                                                                                                            |
| `email`        | Must be unique within the same account                                                                                                                                            |
| `country_code` | Two-letter country code (ISO 3166-1 alpha-2)                                                                                                                                      |
| `phone_number` | Must be unique within the same account. Length validated by country — see [Phone number validation rules](/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder) |

**Optional fields:** `date_of_birth`, `gender`, `nationality`, `residential_address`, `identity`, `kyc_verification`, `document_type`, `document`

<Warning>
  The cardholder's **email** and **phone number** must be unique across all cardholders under the same account. Duplicate values will be rejected.
</Warning>

### Request

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex.chen@example.com",
    "country_code": "SG",
    "phone_number": "91234567"
  }'
```

### Response

```json theme={null}
{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}
```

The result is returned synchronously — no webhook is triggered for cardholder creation.

<Note>
  If the card product requires Enhanced KYC, `cardholder_status` returns `PENDING` instead of `SUCCESS`. The cardholder must complete identity verification before a card can be issued. See the [KYC verification](/card-issuance/v1.6/guide/enhanced-kyc-card-issuance) guide.
</Note>

## Cardholder status

| Status       | Description                                       |
| ------------ | ------------------------------------------------- |
| `SUCCESS`    | Cardholder is active and can be issued cards      |
| `PENDING`    | Awaiting KYC verification                         |
| `INCOMPLETE` | KYC documents are missing or require resubmission |
| `FAILED`     | Onboarding failed                                 |

## Retrieve a cardholder

Use the [Retrieve Cardholder](/card-issuance/v1.6/api-reference/retrieve-cardholder) endpoint to get full cardholder details.

```bash theme={null}
curl https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders/25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -H "x-auth-token: YOUR_API_TOKEN"
```

```json theme={null}
{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "email": "alex.chen@example.com",
  "first_name": "Alex",
  "last_name": "Chen",
  "country_code": "SG",
  "phone_number": "91234567",
  "number_of_cards": 1,
  "cardholder_status": "SUCCESS",
  "create_time": "2026-04-10T18:03:47+08:00"
}
```

## List cardholders

Use the [List Cardholders](/card-issuance/v1.6/api-reference/list-cardholders) endpoint to paginate through all cardholders. You can filter by `cardholder_status`.

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_number=1&page_size=10" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

## Update a cardholder

Use the [Update Cardholder](/card-issuance/v1.6/api-reference/update-cardholder) endpoint to modify cardholder details. You can update `email`, `phone_number`, `country_code`, `date_of_birth`, `gender`, `nationality`, `residential_address`, and identity/KYC fields.

<Warning>
  `first_name` and `last_name` cannot be updated after creation.
</Warning>

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders/25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "SG",
    "phone_number": "98765432"
  }'
```

## Related

* [KYC verification](/card-issuance/v1.6/guide/enhanced-kyc-card-issuance) — Enhanced KYC flow for card products that require identity verification
* [Phone number validation rules](/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder) — Country-specific phone number length requirements
* [Create Cardholder API](/card-issuance/v1.6/api-reference/create-cardholder)
* [Cardholder webhooks](/card-issuance/v1.6/webhooks/cardholder-kyc-status-changed)