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

# Cardholders

> Create cardholders, complete KYC verification, and issue virtual cards. A cardholder must be KYC-verified before cards can be issued.

# Cardholders

A cardholder represents a person who will receive and use virtual cards issued through your Issuing app. After creation the cardholder is active but **unverified** — KYC verification is required before any card can be issued.

```
Create Cardholder → Verify Identity (KYC) → Issue Card(s)
```

## What a Cardholder Has

| Field         | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `id`          | Unique cardholder ID (e.g. `CH1a2b3c4d5e6f`)                     |
| `externalId`  | Your own ID for this person — map to your user database          |
| Personal info | First name, last name, email, phone, date of birth, gender       |
| Address       | Street, city, state, country, postal code                        |
| `status`      | Account status: `ACTIVE`, `INACTIVE`, or `SUSPENDED`             |
| `kycStatus`   | Identity verification status — must be `ACCEPTED` to issue cards |
| `metadata`    | Custom key-value data from your platform                         |

## Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Unsubmitted: POST /cardholders\n(status: ACTIVE, kycStatus: UNSUBMITTED)
    Unsubmitted --> Pending: Initiate KYC
    Pending --> Accepted: Verification approved
    Pending --> Rejected: Verification failed
    Rejected --> Pending: Retry verification
    note right of Accepted: Cards can be issued
    Accepted --> Suspended: Manual suspension
    Unsubmitted --> Suspended: Manual suspension
    Suspended --> Unsubmitted: Reactivation
```

## Statuses

### Account Status

| Status      | Description            |
| ----------- | ---------------------- |
| `ACTIVE`    | Normal operating state |
| `INACTIVE`  | Temporarily disabled   |
| `SUSPENDED` | Blocked due to policy  |

<Note>
  Suspending a cardholder does **not** automatically freeze their cards. Manage card statuses separately if needed.
</Note>

### KYC Status

| kycStatus     | Description                         | Can Issue Cards |
| ------------- | ----------------------------------- | --------------- |
| `UNSUBMITTED` | No verification started             | No              |
| `PENDING`     | Verification in progress            | No              |
| `ACCEPTED`    | Identity verified                   | **Yes**         |
| `REJECTED`    | Verification failed — retry allowed | No              |

Cards can only be issued when `status: ACTIVE` **and** `kycStatus: ACCEPTED`.

## Quick Start

```javascript theme={null}
// 1. Create cardholder
const cardholder = await createCardholder({
  firstName: 'Alice',
  lastName: 'Example',
  email: 'john@example.com',
  phone: '+15550001234',
  dateOfBirth: '1990-01-01',
  gender: 'MALE',
  country: 'US'
});
// cardholder.kycStatus === 'UNSUBMITTED' — cannot issue cards yet

// 2. Initiate KYC and redirect cardholder
const kyc = await initiateKycSession(cardholder.id);
redirectTo(kyc.verificationUrl);

// 3. Listen for webhook, then issue card
// Webhook: cardholder.kyc_approved
const card = await createCard({ cardholderId: cardholder.id });
```

See [KYC Verification](/v3/documentation/concepts/cardholders/kyc) for details on the verification paths.

## Integration Patterns

### External ID Mapping

Link cardholders to your existing user database using `externalId`:

```javascript theme={null}
await createCardholder({
  firstName: 'Alice',
  lastName: 'Doe',
  email: 'john@example.com',
  phone: '+15550001234',
  dateOfBirth: '1985-03-20',
  gender: 'MALE',
  country: 'US',
  externalId: 'user_12345'  // your database ID
});
```

### Suspend / Reactivate

```javascript theme={null}
// Suspend a cardholder
PATCH /cardholders/{id}
{ "status": "SUSPENDED" }

// Reactivate
PATCH /cardholders/{id}
{ "status": "ACTIVE" }
```

## Best Practices

<AccordionGroup>
  <Accordion title="Collect Complete Information Upfront">
    Gather all required fields at registration: `firstName`, `lastName`, `email`, `phone`, `dateOfBirth`, `gender`, `country`. Validate email format and use E.164 phone format (+country code + number).
  </Accordion>

  <Accordion title="Start KYC Right After Creation">
    Trigger the KYC flow immediately after cardholder creation so verification completes before the cardholder expects to use a card. Delaying KYC is the most common reason card issuance fails.
  </Accordion>

  <Accordion title="Use External IDs">
    Always set `externalId` to your internal user ID. It makes cardholder lookups and reconciliation straightforward without storing our cardholder IDs in your system.
  </Accordion>
</AccordionGroup>

## Error Codes

| Code                          | Cause                           | Resolution                                     |
| ----------------------------- | ------------------------------- | ---------------------------------------------- |
| `DUPLICATE_EMAIL`             | Email already registered        | Use existing cardholder or a different email   |
| `DUPLICATE_EXTERNAL_ID`       | External ID already used        | Check existing cardholders first               |
| `CARDHOLDER_NOT_VERIFIED`     | KYC not accepted                | Complete KYC verification before issuing cards |
| `CARDHOLDER_HAS_ACTIVE_CARDS` | Cannot delete with active cards | Terminate all cards before deleting            |

## Webhook Events

| Event                  | Description               |
| ---------------------- | ------------------------- |
| `cardholder.created`   | New cardholder registered |
| `cardholder.updated`   | Cardholder info modified  |
| `cardholder.suspended` | Cardholder suspended      |
| `cardholder.activated` | Cardholder reactivated    |

## Endpoints

* `GET /cardholders` — [List cardholders](/v3/api-reference/cardholders/list)
* `POST /cardholders` — [Create cardholder](/v3/api-reference/cardholders/create)
* `GET /cardholders/{id}` — [Get cardholder](/v3/api-reference/cardholders/get)
* `PATCH /cardholders/{id}` — [Update cardholder](/v3/api-reference/cardholders/update)
* `DELETE /cardholders/{id}` — [Delete cardholder](/v3/api-reference/cardholders/delete)