Skip to main content
GET
/
cardholders
List Cardholders
curl --request GET \
  --url https://api.fyatu.com/api/v3/cardholders \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status": 200,
  "message": "Cardholders retrieved successfully",
  "data": {
    "cardholders": [
      {
        "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
        "externalId": "USR-78945",
        "firstName": "James",
        "lastName": "Wilson",
        "email": "[email protected]",
        "phone": "+12025551234",
        "status": "ACTIVE",
        "kycStatus": "VERIFIED",
        "cardsCount": 2,
        "createdAt": "2026-01-10 14:30:00"
      },
      {
        "id": "ch_9f8e7d6c5b4a3210fedcba9876543210",
        "externalId": null,
        "firstName": "Sarah",
        "lastName": "Johnson",
        "email": "[email protected]",
        "phone": "+14155559876",
        "status": "ACTIVE",
        "kycStatus": "PENDING",
        "cardsCount": 1,
        "createdAt": "2026-01-05 09:15:00"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 20,
      "totalItems": 2,
      "totalPages": 1
    }
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-01-17T10:00:00+00:00"
  }
}

​
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

ParameterTypeDescription
pageintegerPage number (default: 1)
limitintegerItems per page (default: 20, max: 100)
statusstringFilter by status (ACTIVE, INACTIVE, SUSPENDED)
kycStatusstringFilter by KYC status (UNSUBMITTED, PENDING, VERIFIED, REJECTED)
searchstringSearch by name or email (partial match)

​
Response

FieldTypeDescription
cardholdersarrayList of cardholder objects
paginationobjectPagination info

​
Cardholder Object (Summary)

FieldTypeDescription
idstringUnique cardholder identifier
externalIdstringYour system’s identifier (nullable)
firstNamestringFirst name
lastNamestringLast name
emailstringEmail address
phonestringPhone number
statusstringCardholder status
kycStatusstringKYC verification status
cardsCountintegerNumber of active cards
createdAtstringCreation timestamp

​
Example Usage

<?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";

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "Cardholders retrieved successfully",
  "data": {
    "cardholders": [
      {
        "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
        "externalId": "USR-78945",
        "firstName": "James",
        "lastName": "Wilson",
        "email": "[email protected]",
        "phone": "+12025551234",
        "status": "ACTIVE",
        "kycStatus": "VERIFIED",
        "cardsCount": 2,
        "createdAt": "2026-01-10 14:30:00"
      },
      {
        "id": "ch_9f8e7d6c5b4a3210fedcba9876543210",
        "externalId": null,
        "firstName": "Sarah",
        "lastName": "Johnson",
        "email": "[email protected]",
        "phone": "+14155559876",
        "status": "ACTIVE",
        "kycStatus": "PENDING",
        "cardsCount": 1,
        "createdAt": "2026-01-05 09:15:00"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 20,
      "totalItems": 2,
      "totalPages": 1
    }
  },
  "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
Use the search parameter to quickly find cardholders by name or email. The search is case-insensitive and matches partial strings.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Query Parameters

​
page
integer
default:1

Page number (default: 1)

​
limit
integer
default:20

Items per page (default: 20, max: 100)

Required range: x <= 100
​
status
enum<string>

Filter by cardholder status

Available options:
ACTIVE,
INACTIVE,
SUSPENDED
​
kycStatus
enum<string>

Filter by KYC verification status

Available options:
UNSUBMITTED,
PENDING,
VERIFIED,
REJECTED
​
search
string

Search by name or email (partial match)

Response

Cardholders retrieved successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
Example:

"Cardholders retrieved successfully"

​
data
object
​
meta
object