> ## 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.

# Get Cardholder

> Retrieve full profile details for a cardholder by ID. GET /cardholders/{id}. Requires cardholders:read scope.

## Overview

Returns the full profile of a single cardholder, including address, KYC status, and spend statistics. The `kycRejectionReason` field is only present when `kycStatus` is `REJECTED`. The `terminatedAt` field is only present when `status` is `TERMINATED`. Both `APPROVED` and `WAIVED` cardholders can be issued cards.

## Path Parameters

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `id`      | string | The cardholder ID (prefix `chl_`) |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678 \
    -H "Authorization: Bearer $FYATU_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    'https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678',
    { headers: { 'Authorization': `Bearer ${process.env.FYATU_API_KEY}` } }
  );
  const body = await resp.json();
  const cardholder = body.data;
  console.log(cardholder.kycStatus);   // "APPROVED"
  console.log(cardholder.totalCards);  // 2
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.get(
      'https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678',
      headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'}
  )
  cardholder = resp.json()['data']
  print(cardholder['kycStatus'])
  ```
</CodeGroup>

## Success Response (200)

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "programId":     "prg_01HXYZ9876ABCDEF0000",
    "firstName":     "John",
    "lastName":      "Smith",
    "email":         "john.smith@example.com",
    "phone":         "+12025551234",
    "dateOfBirth":   "1990-05-15",
    "nationality":   "US",
    "address": {
      "line1":      "123 Main Street",
      "line2":      "Apt 4B",
      "city":       "Newark",
      "state":      "Delaware",
      "postalCode": "19701",
      "country":    "US"
    },
    "externalId":    "usr_123456",
    "metadata":      { "plan": "premium" },
    "status":        "ACTIVE",
    "kycStatus":     "APPROVED",
    "kycVerifiedAt": "2026-05-01T09:05:00Z",
    "totalCards":    2,
    "totalSpendCents": 125000,
    "suspendedAt":   null,
    "createdAt":     "2026-05-01T09:00:00Z",
    "updatedAt":     "2026-05-01T09:05:00Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

## Conditional Fields

| Field                | Present when                                                              |
| -------------------- | ------------------------------------------------------------------------- |
| `kycRejectionReason` | `kycStatus` is `REJECTED`                                                 |
| `kycVerifiedAt`      | `kycStatus` is `APPROVED`; `null` for `PENDING`, `WAIVED`, and `REJECTED` |
| `terminatedAt`       | `status` is `TERMINATED`                                                  |

### KYC Waived Example

On MINIMAL programs, `kycStatus` is `WAIVED` immediately after creation — the cardholder has not been identity-verified but is allowed to hold cards. No `kycVerifiedAt` is set.

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":     "WAIVED",
    "kycVerifiedAt": null
  },
  "meta": { "requestId": "req_01HXY123456ABCDEF", "platform": "Fyatu CaaS", "timestamp": "2026-05-25T10:00:00Z" }
}
```

### KYC Rejected Example

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":      "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":         "REJECTED",
    "kycRejectionReason": "Document expired or unreadable",
    "kycVerifiedAt":     "2026-05-01T09:05:00Z"
  },
  "meta": { "requestId": "req_01HXY123456ABCDEF", "platform": "Fyatu CaaS", "timestamp": "2026-05-22T10:00:00Z" }
}
```

## Error Codes

| Code                   | HTTP | Cause                                                    |
| ---------------------- | ---- | -------------------------------------------------------- |
| `CARDHOLDER_NOT_FOUND` | 404  | Cardholder does not exist or belongs to another business |
| `INSUFFICIENT_SCOPE`   | 403  | Key lacks `cardholders:read` scope                       |


## OpenAPI

````yaml v3.20/openapi.json GET /cardholders/{id}
openapi: 3.1.0
info:
  title: FYATU CaaS API v3.20
  description: >-
    FYATU Cards-as-a-Service API — API key authentication, Cardholder
    lifecycle, Card issuance, Transactions, Webhooks, and Programs.
  version: 3.20.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3.20
    description: >-
      FYATU CaaS API — the environment (LIVE or SANDBOX) is determined by the
      API key, not the URL
security:
  - BearerAuth: []
tags:
  - name: Meta
    description: Liveness, account info, and supported event types
  - name: Account
    description: Account-level balance and funding status
  - name: Programs
    description: Read card program configuration
  - name: Cardholders
    description: Create and manage cardholder profiles
  - name: Cards
    description: Issue, fund, freeze, and terminate virtual cards
  - name: Transactions
    description: Read-only card transaction history
  - name: Webhooks
    description: Manage webhook endpoints for real-time event delivery
  - name: Products
    description: Read card product configurations
paths:
  /cardholders/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: chl_01HXYZ1234ABCDEF5678
    get:
      tags:
        - Cardholders
      summary: Get a cardholder
      description: Retrieve full details for a single cardholder.
      operationId: getCardholder
      responses:
        '200':
          description: Cardholder retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardholderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CardholderResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Cardholder retrieved
        data:
          $ref: '#/components/schemas/Cardholder'
        meta:
          $ref: '#/components/schemas/Meta'
    Cardholder:
      type: object
      properties:
        cardholderId:
          type: string
          example: chl_01HXYZ1234ABCDEF5678
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        email:
          type: string
          format: email
          example: john.smith@example.com
        phone:
          type: string
          nullable: true
          example: '+12025551234'
        dateOfBirth:
          type: string
          format: date
          example: '1990-05-15'
        nationality:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
        address:
          $ref: '#/components/schemas/Address'
        kycDocument:
          $ref: '#/components/schemas/KycDocument'
          nullable: true
        externalId:
          type: string
          nullable: true
          example: usr_123456
        metadata:
          type: object
          nullable: true
          example:
            plan: premium
        status:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
            - TERMINATED
          example: ACTIVE
        kycStatus:
          type: string
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          example: APPROVED
        kycVerifiedAt:
          type: string
          format: date-time
          nullable: true
          example: '2026-05-10T14:23:00Z'
        kycRejectionReason:
          type: string
          nullable: true
          description: Only present when kycStatus is REJECTED
          example: null
        totalCards:
          type: integer
          example: 2
        suspendedAt:
          type: string
          format: date-time
          nullable: true
          example: null
        terminatedAt:
          type: string
          format: date-time
          nullable: true
          description: Only present when status is TERMINATED
          example: null
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T09:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-05-10T14:23:00Z'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_a1b2c3d4e5f6a7b8c9d0e1f2
        platform:
          type: string
          example: Fyatu CaaS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-22T15:00:00Z'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 422
        message:
          type: string
          example: Human readable message
        error:
          $ref: '#/components/schemas/ErrorBody'
        meta:
          $ref: '#/components/schemas/Meta'
    Address:
      type: object
      properties:
        address:
          type: string
          example: 123 Main Street, Apt 4B
        city:
          type: string
          example: Newark
        state:
          type: string
          nullable: true
          example: Delaware
        postalCode:
          type: string
          nullable: true
          example: '19701'
        country:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
      required:
        - address
        - city
        - country
    KycDocument:
      type: object
      description: >-
        Identity document details for KYC verification. Optional on create;
        patchable via PATCH. Not locked after KYC approval.
      properties:
        documentType:
          type: string
          enum:
            - PASSPORT
            - NATIONAL_ID
            - DRIVERS_LICENSE
            - RESIDENCE_PERMIT
          example: PASSPORT
        documentNumber:
          type: string
          example: AB123456
        issuingCountry:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
        frontUrl:
          type: string
          format: uri
          example: https://storage.example.com/doc-front.jpg
        backUrl:
          type: string
          format: uri
          nullable: true
          description: Not required for passports
          example: null
        selfieUrl:
          type: string
          format: uri
          example: https://storage.example.com/selfie.jpg
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        detail:
          type: string
          example: dateOfBirth must be in YYYY-MM-DD format
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: API key missing
              value:
                success: false
                status: 401
                message: API key is required
                error:
                  code: AUTH_TOKEN_MISSING
                  detail: API key is required
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
            invalid:
              summary: API key invalid
              value:
                success: false
                status: 401
                message: Invalid API key
                error:
                  code: AUTH_TOKEN_INVALID
                  detail: Invalid API key
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
    Forbidden:
      description: Scope denied or business suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 403
            message: Scope denied
            error:
              code: INSUFFICIENT_SCOPE
              detail: This endpoint requires the cards:write scope
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
    NotFound:
      description: Resource not found or does not belong to your business
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 429
            message: Rate limit exceeded
            error:
              code: RATE_LIMIT_EXCEEDED
              detail: Too many requests
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 500
            message: Internal error
            error:
              code: INTERNAL_ERROR
              detail: An unexpected error occurred
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
        <key>`.

````