Get a cardholder
curl --request GET \
--url https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"status": 200,
"message": "Cardholder retrieved",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"phone": "+12025551234",
"dateOfBirth": "1990-05-15",
"nationality": "US",
"gender": "MALE",
"address": {
"address": "123 Main Street, Apt 4B",
"city": "Newark",
"country": "US",
"state": "Delaware",
"postalCode": "19701"
},
"kycDocument": {
"documentType": "PASSPORT",
"documentNumber": "••••3456",
"issuingCountry": "US",
"issuingDate": "2019-03-04",
"expiryDate": "2029-03-03"
},
"externalId": "usr_123456",
"metadata": {
"plan": "premium"
},
"status": "ACTIVE",
"kycStatus": "APPROVED",
"kycVerifiedAt": "2026-05-10T14:23:00Z",
"kycRejectionReason": null,
"totalCards": 2,
"suspendedAt": null,
"terminatedAt": null,
"createdAt": "2026-05-01T09:00:00Z",
"updatedAt": "2026-05-10T14:23:00Z",
"programEligibility": [
{
"programCode": "FYT-USD-02",
"programName": "USD Global Tier 2",
"eligible": false,
"requiresVerification": true,
"reason": "<string>",
"bins": [
{
"binCode": "SGVISAV01",
"binName": "Virtual Card - Singapore BIN",
"bin": "49372410",
"issuingCountry": "SG",
"scheme": "VISA",
"formFactor": "VIRTUAL",
"requiresVerification": true,
"eligible": true,
"reason": "<string>",
"verificationStatus": "NOT_SUBMITTED",
"canSubmit": true,
"verificationMessage": "<string>"
}
]
}
]
},
"meta": {
"requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-22T15:00:00Z"
}
}Cardholders
Get Cardholder
Retrieve full profile details for a cardholder by ID. GET /cardholders/. Requires cardholders:read scope.
GET
/
cardholders
/
{id}
Get a cardholder
curl --request GET \
--url https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"status": 200,
"message": "Cardholder retrieved",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"phone": "+12025551234",
"dateOfBirth": "1990-05-15",
"nationality": "US",
"gender": "MALE",
"address": {
"address": "123 Main Street, Apt 4B",
"city": "Newark",
"country": "US",
"state": "Delaware",
"postalCode": "19701"
},
"kycDocument": {
"documentType": "PASSPORT",
"documentNumber": "••••3456",
"issuingCountry": "US",
"issuingDate": "2019-03-04",
"expiryDate": "2029-03-03"
},
"externalId": "usr_123456",
"metadata": {
"plan": "premium"
},
"status": "ACTIVE",
"kycStatus": "APPROVED",
"kycVerifiedAt": "2026-05-10T14:23:00Z",
"kycRejectionReason": null,
"totalCards": 2,
"suspendedAt": null,
"terminatedAt": null,
"createdAt": "2026-05-01T09:00:00Z",
"updatedAt": "2026-05-10T14:23:00Z",
"programEligibility": [
{
"programCode": "FYT-USD-02",
"programName": "USD Global Tier 2",
"eligible": false,
"requiresVerification": true,
"reason": "<string>",
"bins": [
{
"binCode": "SGVISAV01",
"binName": "Virtual Card - Singapore BIN",
"bin": "49372410",
"issuingCountry": "SG",
"scheme": "VISA",
"formFactor": "VIRTUAL",
"requiresVerification": true,
"eligible": true,
"reason": "<string>",
"verificationStatus": "NOT_SUBMITTED",
"canSubmit": true,
"verificationMessage": "<string>"
}
]
}
]
},
"meta": {
"requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-22T15:00:00Z"
}
}Overview
Returns the full profile of a single cardholder, including address, KYC status, and which programmes can issue for it. ThekycRejectionReason field is only present when kycStatus is REJECTED. The terminatedAt field is only present when status is TERMINATED.
KYC Status
| Status | Meaning | Can be issued a card |
|---|---|---|
PENDING | Created, nothing submitted for verification yet | No |
SUBMITTED | Sent for verification, awaiting an answer | No |
APPROVED | Verified | On every programme |
REJECTED | Verification was unsuccessful. PATCH the cardholder to correct it and it is checked again | No |
WAIVED | Legacy status, no longer assigned. Not verified | No — submit a kycDocument to have the cardholder verified |
APPROVED cardholder can be issued a card, on every programme, every BIN and under
every KYC module (since 7 November 2026). The cardholder is declared to the issuer exactly as their
identity document shows — their own document, under the country that issued it.
WAIVED is a legacy status that is no longer assigned: we hold no identity document for the
cardholder. A cardholder still carrying it keeps the cards they already hold but cannot be issued a
new one until their kycDocument is submitted and approved.
Programme Eligibility
programEligibility answers whether this cardholder can be issued a card — per BIN, and summarised
per programme. It is returned on this endpoint only, not on GET /cardholders.
The BIN is where the decision is made. BINs on one programme do not agree about what they require:
a programme can hold one BIN that does not require the identity document at issuance alongside others that do.
A programme is eligible when at least one of its BINs is.
"programEligibility": [
{
"programCode": "FYT-USD-01",
"programName": "USD Virtual - Global",
"eligible": true,
"requiresVerification": false,
"bins": [
{
"binCode": "USVISAV01",
"binName": "Virtual Card - Visa",
"bin": "493724",
"issuingCountry": "US",
"scheme": "VISA",
"formFactor": "VIRTUAL",
"requiresVerification": false,
"eligible": true
}
]
},
{
"programCode": "FYT-USD-02",
"programName": "USD Multi-Region - Visa & Mastercard",
"eligible": true,
"requiresVerification": true,
"bins": [
{
"binCode": "SGVISAV01",
"binName": "Virtual Card - Singapore BIN",
"bin": "49372410",
"issuingCountry": "SG",
"scheme": "VISA",
"formFactor": "VIRTUAL",
"requiresVerification": false,
"eligible": true
},
{
"binCode": "HKMCV01",
"binName": "Virtual Card - Hong Kong BIN (Mastercard)",
"bin": "524013",
"issuingCountry": "HK",
"scheme": "MASTERCARD",
"formFactor": "VIRTUAL",
"requiresVerification": true,
"eligible": false,
"reason": "Needs a verified cardholder. Add identity documents to have this one verified.",
"verificationStatus": "NOT_SUBMITTED",
"canSubmit": true
}
]
}
]
| Field | Description |
|---|---|
eligible | On a BIN, whether a card can be issued from it right now. On a programme, whether any of its BINs can |
requiresVerification | On a BIN, whether it needs a verified cardholder. On a programme, whether any of its BINs does — a summary, which does not by itself close the programme |
bins | Every issuable BIN on the programme, each with its own answer |
bin | The BIN number, as printed on cards issued from it. Absent where the registry has no number recorded |
issuingCountry | ISO 3166-1 alpha-2 country the BIN issues from |
reason | Present only when not eligible; says what to do |
verificationStatus | Where this BIN’s own verification stands: NOT_SUBMITTED, IN_REVIEW, REJECTED or VERIFIED. Absent on a BIN whose issuer keeps no cardholder record of its own: there the cardholder’s kycStatus decides, and it must be APPROVED |
canSubmit | Whether submitting this cardholder to this BIN would do anything now. Absent once verified, and while your own verification has not concluded |
verificationMessage | What came back about this cardholder on this BIN — why a review failed. Absent when nothing was said |
A cardholder is registered per BIN
Verification is not held once for your account. The issuers behind different BINs each keep their own record of a cardholder and run their own check, so a cardholder verified for one BIN is unknown to the next and has to be registered there too. That is why the answer is per BIN, and whyverificationStatus can differ across BINs of the same
programme: one VERIFIED, its neighbour NOT_SUBMITTED. A cardholder’s own kycStatus is our
verification of them and answers for neither.
Where canSubmit is true, POST /cardholders/{id}/submit
registers them on that BIN.
What a BIN expects
A BIN that requires verification takes anAPPROVED cardholder and nothing else.
Your KYC module decides who verifies the cardholder, never whether they must be verified:
| Your KYC module | Who verifies | Cardholder statuses that can be issued |
|---|---|---|
| Managed (pay as you go) | FYATU, per cardholder | APPROVED |
| Delegated (subscription) | You submit the kycDocument; FYATU checks it | APPROVED |
PENDING, SUBMITTED, REJECTED and WAIVED are never eligible.
Country restrictions are separate and are applied when a card is issued, not here. A cardholder
whose nationality or country of residence is restricted on a product’s BIN is refused with
422 CARDHOLDER_COUNTRY_RESTRICTED, naming the country.Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The cardholder ID (prefix chl_) |
Example
curl https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678 \
-H "Authorization: Bearer $FYATU_API_KEY"
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
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'])
Success Response (200)
{
"success": true,
"status": 200,
"message": "Cardholder retrieved",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"phone": "+12025551234",
"dateOfBirth": "1990-05-15",
"nationality": "US",
"address": {
"address": "123 Main Street, Apt 4B",
"city": "Newark",
"state": "Delaware",
"postalCode": "19701",
"country": "US"
},
"kycDocument": null,
"externalId": "usr_123456",
"metadata": {
"plan": "premium"
},
"status": "ACTIVE",
"kycStatus": "APPROVED",
"gender": "MALE",
"kycVerifiedAt": "2026-05-01T09:05:00Z",
"totalCards": 2,
"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"
}
}
What kycDocument looks like on the way back
Changed on 19 October 2026. The returned
kycDocument no longer carries frontUrl, backUrl
or selfieUrl, and documentNumber is masked to its last four characters. The fields you
send on create and on PATCH are unchanged."kycDocument": {
"documentType": "PASSPORT",
"documentNumber": "••••3456",
"issuingCountry": "US",
"issuingDate": "2019-03-04",
"expiryDate": "2029-03-03"
}
- A profile fetch should not be a way to open somebody’s passport. Anything holding one of your
API keys could page
/cardholdersand fetch each record, and every response used to hand back a working link to that person’s identity images. - The document number is the field used to impersonate its holder. The last four is enough to confirm the document we hold is the one you sent, which is the only thing you need it for.
kycDocument is null outright, whatever was submitted before. When a
cardholder is deleted their identity images stop being reachable to anyone, including through our
own admin tools — so there is nothing for us to return and nothing for anyone to ask us to produce.
If a review screen of your own genuinely needs to display a document, contact support and say which
flow needs it. It is granted per account and through an endpoint that records every read.
Conditional Fields
| Field | Present when |
|---|---|
kycRejectionReason | kycStatus is REJECTED |
kycVerifiedAt | Set when kycStatus is APPROVED (the verification timestamp), or on a WAIVED cardholder (when KYC was waived); null for PENDING and REJECTED |
terminatedAt | status is TERMINATED |
Legacy WAIVED Example
A WAIVED cardholder (legacy status) has not been identity-verified: kycVerifiedAt is not a
verification date. They cannot be issued a card until a
kycDocument is submitted and approved.
{
"success": true,
"status": 200,
"message": "Cardholder retrieved",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"kycStatus": "WAIVED",
"kycVerifiedAt": "2026-05-25T10:00:00Z"
},
"meta": {
"requestId": "req_01HXY123456ABCDEF",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-25T10:00:00Z"
}
}
KYC Rejected Example
{
"success": true,
"status": 200,
"message": "Cardholder retrieved",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"kycStatus": "REJECTED",
"kycRejectionReason": "Document expired or unreadable",
"kycVerifiedAt": null
},
"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 |

