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

# List Cardholders

> List all cardholders in your Fyatu card program with pagination and KYC status filtering. GET /cardholders.

## Overview

Retrieve a paginated list of cardholders associated with your application. Use filters to narrow down results by status, KYC status, or search terms.

## Query Parameters

| Parameter   | Type    | Description                                                     |
| ----------- | ------- | --------------------------------------------------------------- |
| `page`      | integer | Page number (default: 1)                                        |
| `limit`     | integer | Items per page (default: 20, max: 100)                          |
| `status`    | string  | Filter by status (ACTIVE, INACTIVE, SUSPENDED)                  |
| `kycStatus` | string  | Filter by KYC status (UNSUBMITTED, PENDING, VERIFIED, REJECTED) |
| `search`    | string  | Search by name or email (partial match)                         |

## Response

| Field         | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `cardholders` | array  | List of cardholder objects |
| `pagination`  | object | Pagination info            |

### Cardholder Object (Summary)

| Field        | Type    | Description                         |
| ------------ | ------- | ----------------------------------- |
| `id`         | string  | Unique cardholder identifier        |
| `externalId` | string  | Your system's identifier (nullable) |
| `firstName`  | string  | First name                          |
| `lastName`   | string  | Last name                           |
| `email`      | string  | Email address                       |
| `phone`      | string  | Phone number                        |
| `status`     | string  | Cardholder status                   |
| `kycStatus`  | string  | KYC verification status             |
| `cardsCount` | integer | Number of active cards              |
| `createdAt`  | string  | Creation timestamp                  |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  // Get active cardholders with verified KYC
  $params = http_build_query([
      'status' => 'ACTIVE',
      'kycStatus' => 'VERIFIED',
      'limit' => 50
  ]);

  $response = file_get_contents(
      "https://api.fyatu.com/api/v3/cardholders?{$params}",
      false,
      stream_context_create([
          'http' => [
              'method' => 'GET',
              'header' => 'Authorization: Bearer ' . $accessToken
          ]
      ])
  );

  $result = json_decode($response, true);

  foreach ($result['data']['cardholders'] as $ch) {
      echo "{$ch['firstName']} {$ch['lastName']} - {$ch['email']} ({$ch['kycStatus']})\n";
  }

  // Pagination info
  $pagination = $result['data']['pagination'];
  echo "Page {$pagination['currentPage']} of {$pagination['totalPages']}\n";
  ```

  ```javascript Node.js theme={null}
  // Get active cardholders with verified KYC
  const params = new URLSearchParams({
    status: 'ACTIVE',
    kycStatus: 'VERIFIED',
    limit: '50'
  });

  const response = await fetch(
    `https://api.fyatu.com/api/v3/cardholders?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  const result = await response.json();

  for (const ch of result.data.cardholders) {
    console.log(`${ch.firstName} ${ch.lastName} - ${ch.email} (${ch.kycStatus})`);
  }

  // Pagination info
  const { currentPage, totalPages } = result.data.pagination;
  console.log(`Page ${currentPage} of ${totalPages}`);
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholders retrieved successfully",
  "data": {
    "cardholders": [
      {
        "id": "ch_a1b2c3d4e5f6",
        "externalId": "EXT-0001",
        "firstName": "Alice",
        "lastName": "Example",
        "email": "alice@example.com",
        "phone": "+15550001234",
        "status": "ACTIVE",
        "kycStatus": "VERIFIED",
        "cardsCount": 1,
        "createdAt": "2026-01-10 14:30:00"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 20,
      "totalItems": 47,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-01-17T10:00:00+00:00"
  }
}
```

## Filtering Tips

### By KYC Status

```
GET /cardholders?kycStatus=VERIFIED
```

### Search by Name or Email

```
GET /cardholders?search=john
```

### Combine Filters

```
GET /cardholders?status=ACTIVE&kycStatus=VERIFIED&limit=100
```

<Tip>
  Use the `search` parameter to quickly find cardholders by name or email. The search is case-insensitive and matches partial strings.
</Tip>


## OpenAPI

````yaml v3/openapi.json GET /cardholders
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /cardholders:
    get:
      tags:
        - Cardholders
      summary: List Cardholders
      description: >-
        Retrieve a paginated list of cardholders associated with your
        application. Use filters to narrow down results by status, KYC status,
        or search terms.
      operationId: listCardholders
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: 'Page number (default: 1)'
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
          description: 'Items per page (default: 20, max: 100)'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - ACTIVE
              - INACTIVE
              - SUSPENDED
          description: Filter by cardholder status
        - name: kycStatus
          in: query
          schema:
            type: string
            enum:
              - UNSUBMITTED
              - SUBMITTED
              - ACCEPTED
              - REJECTED
          description: Filter by KYC verification status
        - name: search
          in: query
          schema:
            type: string
          description: Search by name or email (partial match)
      responses:
        '200':
          description: Cardholders retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardholderListResponse'
              example:
                success: true
                status: 200
                message: Cardholders retrieved successfully
                data:
                  cardholders:
                    - id: ch_a1b2c3d4e5f6
                      externalId: EXT-0001
                      firstName: Alice
                      lastName: Example
                      email: alice@example.com
                      phone: '+15550001234'
                      status: ACTIVE
                      kycStatus: ACCEPTED
                      cardsCount: 1
                      createdAt: '2026-01-10T14:30:00Z'
                  pagination:
                    currentPage: 1
                    itemsPerPage: 20
                    totalItems: 47
                    totalPages: 3
                meta:
                  requestId: req_a1b2c3d4e5f6
                  timestamp: '2026-01-17T10:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - BearerAuth: []
components:
  schemas:
    CardholderListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Cardholders retrieved successfully
        data:
          type: object
          properties:
            cardholders:
              type: array
              items:
                $ref: '#/components/schemas/CardholderListItem'
            pagination:
              $ref: '#/components/schemas/PaginationAlt'
        meta:
          $ref: '#/components/schemas/Meta'
    CardholderListItem:
      type: object
      properties:
        id:
          type: string
          description: Unique cardholder identifier
          example: ch_1a2b3c4d5e6f7890abcdef1234567890
        externalId:
          type: string
          nullable: true
          description: Your system's identifier
        firstName:
          type: string
          description: First name
        lastName:
          type: string
          description: Last name
        email:
          type: string
          description: Email address
        phone:
          type: string
          description: Phone number
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - SUSPENDED
          description: Cardholder status
        kycStatus:
          type: string
          enum:
            - UNSUBMITTED
            - SUBMITTED
            - ACCEPTED
            - REJECTED
          description: KYC verification status
        cardsCount:
          type: integer
          description: Number of active cards
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
    PaginationAlt:
      type: object
      properties:
        currentPage:
          type: integer
        itemsPerPage:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 401
            message: Unable to identify business
            error:
              code: AUTH_TOKEN_INVALID
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````