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

> Retrieve a paginated list of cardholders for your business. GET /cardholders. Requires cardholders:read scope.

## Overview

Returns a paginated list of cardholders for your business, scoped to the API key's environment (`LIVE` or `SANDBOX`). Supports filtering by status and free-text search.

## Query Parameters

| Parameter   | Type    | Default | Description                                         |
| ----------- | ------- | ------- | --------------------------------------------------- |
| `limit`     | integer | 20      | Results per page (max 100)                          |
| `offset`    | integer | 0       | Number of records to skip                           |
| `status`    | string  | —       | Filter by `ACTIVE`, `SUSPENDED`, or `TERMINATED`    |
| `programId` | string  | —       | Filter to a specific program                        |
| `search`    | string  | —       | Search name, email, or `externalId` (max 100 chars) |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.fyatu.com/api/v3.20/cardholders \
    -H "Authorization: Bearer $FYATU_API_KEY" \
    -d limit=20 \
    -d offset=0 \
    -d status=ACTIVE
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ limit: '20', offset: '0', status: 'ACTIVE' });
  const resp = await fetch(
    `https://api.fyatu.com/api/v3.20/cardholders?${params}`,
    { headers: { 'Authorization': `Bearer ${process.env.FYATU_API_KEY}` } }
  );
  const body = await resp.json();
  console.log(`${body.pagination.total} cardholders, showing ${body.data.length}`);
  ```

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

  resp = requests.get(
      'https://api.fyatu.com/api/v3.20/cardholders',
      headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
      params={'limit': 20, 'offset': 0, 'status': 'ACTIVE'}
  )
  body = resp.json()
  print(body['pagination']['total'], 'total cardholders')
  ```
</CodeGroup>

## Success Response (200)

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholders retrieved",
  "data": [
    {
      "cardholderId": "chl_01HXYZ1234ABCDEF5678",
      "programId":    "prg_01HXYZ9876ABCDEF0000",
      "firstName":    "John",
      "lastName":     "Smith",
      "email":        "john.smith@example.com",
      "phone":        "+12025551234",
      "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"
    }
  ],
  "pagination": {
    "total":   47,
    "limit":   20,
    "offset":  0,
    "hasMore": true
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

<Info>
  Call `GET /cardholders/{id}` for the full profile including address, date of birth, nationality, and metadata.
</Info>

## Iterating All Pages

```javascript Node.js — iterate all pages theme={null}
async function* listAllCardholders(apiKey) {
  let offset = 0;
  const limit = 100;

  while (true) {
    const resp = await fetch(
      `https://api.fyatu.com/api/v3.20/cardholders?limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const body = await resp.json();
    yield* body.data;

    if (!body.pagination.hasMore) break;
    offset += limit;
  }
}

for await (const ch of listAllCardholders(process.env.FYATU_API_KEY)) {
  console.log(ch.cardholderId, ch.kycStatus);
}
```

## Error Codes

| Code                 | HTTP | Cause                                                     |
| -------------------- | ---- | --------------------------------------------------------- |
| `VALIDATION_ERROR`   | 422  | Invalid `status` value or `search` exceeds 100 characters |
| `INSUFFICIENT_SCOPE` | 403  | Key lacks `cardholders:read` scope                        |
| `INTERNAL_ERROR`     | 500  | Server error                                              |


## OpenAPI

````yaml v3.20/openapi.json GET /cardholders
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:
    get:
      tags:
        - Cardholders
      summary: List cardholders
      description: >-
        Returns a paginated list of cardholders for your business, scoped to the
        API key's environment.
      operationId: listCardholders
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: status
          in: query
          schema:
            type: string
            enum:
              - ACTIVE
              - SUSPENDED
              - TERMINATED
        - name: programId
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
            maxLength: 100
      responses:
        '200':
          description: Cardholders retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardholderListResponse'
              example:
                success: true
                status: 200
                message: Cardholders retrieved
                data:
                  - cardholderId: chl_01HXYZ1234ABCDEF5678
                    firstName: John
                    lastName: Smith
                    email: john.smith@example.com
                    phone: '+12025551234'
                    status: ACTIVE
                    kycStatus: APPROVED
                    externalId: usr_123456
                    totalCards: 2
                    createdAt: '2026-05-01T09:00:00Z'
                pagination:
                  total: 47
                  limit: 20
                  offset: 0
                  hasMore: true
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CardholderListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Cardholders retrieved
        data:
          type: array
          items:
            $ref: '#/components/schemas/CardholderListItem'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/Meta'
    CardholderListItem:
      type: object
      properties:
        cardholderId:
          type: string
          example: chl_01HXYZ1234ABCDEF5678
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        email:
          type: string
          example: john.smith@example.com
        phone:
          type: string
          nullable: true
          example: '+12025551234'
        status:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
            - TERMINATED
          example: ACTIVE
        kycStatus:
          type: string
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          example: APPROVED
        externalId:
          type: string
          nullable: true
          example: usr_123456
        totalCards:
          type: integer
          example: 2
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T09:00:00Z'
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 47
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0
        hasMore:
          type: boolean
          example: true
    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'
    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'
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 422
            message: Validation failed
            error:
              code: VALIDATION_ERROR
              detail: dateOfBirth must be in YYYY-MM-DD format
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
    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>`.

````