Skip to main content
POST
/
cardholders
Create Cardholder
curl --request POST \
  --url https://api.fyatu.com/api/v3/cardholders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "EXT-0001",
  "firstName": "Alice",
  "lastName": "Example",
  "email": "alice@example.com",
  "phone": "+15550001234",
  "dateOfBirth": "1990-05-15",
  "gender": "MALE",
  "address": "123 Main Street, Apt 4B",
  "city": "Newark",
  "state": "Delaware",
  "country": "US",
  "zipCode": "000000",
  "kyc": {
    "documentType": "PASSPORT",
    "documentNumber": "AB1234567",
    "idFrontUrl": "https://storage.example.com/docs/passport_front.jpg",
    "idBackUrl": "https://storage.example.com/docs/passport_back.jpg",
    "idSelfieUrl": "https://storage.example.com/docs/selfie.jpg"
  }
}
'
{
  "success": true,
  "status": 201,
  "message": "Cardholder created successfully",
  "data": {
    "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "externalId": "EXT-0001",
    "firstName": "John",
    "lastName": "Example",
    "email": "alice@example.com",
    "phone": "+15550001234",
    "dateOfBirth": "1990-01-01",
    "gender": "FEMALE",
    "address": {
      "line1": "123 Main Street, Apt 4B",
      "city": "Newark",
      "state": "Delaware",
      "country": "US",
      "zipCode": "000000"
    },
    "document": {
      "type": null,
      "number": null
    },
    "kyc": {
      "status": "UNSUBMITTED",
      "idFrontUrl": null,
      "idBackUrl": null,
      "selfieUrl": null
    },
    "status": "ACTIVE",
    "kycStatus": "UNSUBMITTED",
    "createdAt": "2026-01-17T10:30:00+00:00"
  },
  "meta": {
    "requestId": "req_c1d2e3f4g5h6",
    "timestamp": "2026-01-17T10:30:00+00:00"
  }
}

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.

​
Overview

Create a new cardholder for your card issuing program. The cardholder will be created with ACTIVE status. You can issue cards to the cardholder immediately after creation.

​
Required Fields

FieldTypeDescription
firstNamestringCardholder’s first name (1-100 chars)
lastNamestringCardholder’s last name (1-100 chars)
emailstringEmail address (unique per business)
phonestringPhone number in E.164 format (e.g. +15550001234)
dateOfBirthstringDate of birth (YYYY-MM-DD, must be 18+ years old)
genderstringGender (MALE or FEMALE)
countrystringISO 3166-1 alpha-2 country code (e.g. US)

​
Address Fields

FieldTypeRequiredDescription
addressstringYesStreet address (max 255 chars)
citystringYesCity (max 100 chars)
statestringYesState or province (max 100 chars)
zipCodestringYesPostal/ZIP code (max 20 chars)

​
Optional Fields

FieldTypeDescription
externalIdstringYour platform’s cardholder ID (unique per business, max 100 chars)
metadataobjectArbitrary key-value pairs to store custom data about the cardholder

​
KYC Object (Shared KYC — Enabled Businesses Only)

If your business has Shared KYC enabled, you can include a kyc object at cardholder creation to submit pre-verified identity documents in the same request. The cardholder will immediately be set to PENDING and processed in the background; a cardholder.kyc_approved webhook is dispatched once documents are uploaded and verified. If your business does not have Shared KYC enabled, the kyc object is silently ignored regardless of what is sent.
FieldTypeRequiredDescription
kyc.idFrontUrlstringYesURL to the front image of the ID document
kyc.selfieUrlstringYesURL to a selfie photo of the cardholder
kyc.idBackUrlstringNoURL to the back image of the ID document
kyc.documentTypestringNoPASSPORT, NATIONAL_ID, or DRIVER_LICENSE
For standard identity verification (cardholder completes verification themselves), use Initiate KYC Verification after creating the cardholder.

​
Metadata Object (Optional)

The metadata field accepts any flat JSON object. Use it to store your own data alongside the cardholder — for example, department, employee ID, or tier level. 
{
  "metadata": {
    "department": "Engineering",
    "employee_id": "EMP-1234",
    "tier": "VIP",
    "cost_center": "CC-500"
  }
}
Metadata is returned in all cardholder responses and displayed in the business panel.

​
Example Usage

<?php
$data = [
    'externalId' => 'EXT-0001',
    'firstName' => 'Alice',
    'lastName' => 'Example',
    'email' => 'alice@example.com',
    'phone' => '+15550001234',
    'dateOfBirth' => '1990-01-01',
    'gender' => 'MALE',
    'address' => '123 Main Street, Apt 4B',
    'city' => 'Newark',
    'state' => 'Delaware',
    'country' => 'US',
    'zipCode' => '000000',
    'metadata' => [
        'department' => 'Engineering',
        'employee_id' => 'EMP-1234',
    ],
];

$response = file_get_contents(
    'https://api.fyatu.com/api/v3/cardholders',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => [
                'Authorization: Bearer ' . $accessToken,
                'Content-Type: application/json'
            ],
            'content' => json_encode($data)
        ]
    ])
);

$result = json_decode($response, true);
echo "Created cardholder: " . $result['data']['id'] . "\n";

​
Example Response

{
  "success": true,
  "status": 201,
  "message": "Cardholder created successfully",
  "data": {
    "id": "CH1a2b3c4d5e6f",
    "externalId": "EXT-0001",
    "firstName": "Alice",
    "lastName": "Example",
    "email": "alice@example.com",
    "phone": "+15550001234",
    "dateOfBirth": "1990-01-01",
    "gender": "MALE",
    "address": {
      "line1": "123 Main Street, Apt 4B",
      "city": "Newark",
      "state": "Delaware",
      "country": "US",
      "zipCode": "000000"
    },
    "status": "ACTIVE",
    "metadata": {
      "department": "Engineering",
      "employee_id": "EMP-1234"
    },
    "createdAt": "2026-01-15T21:31:39+00:00"
  },
  "meta": {
    "requestId": "req_2f7fb4227a1007418773122f",
    "timestamp": "2026-01-15T21:31:39+00:00"
  }
}

​
Next Steps

After creating a cardholder, you can:
  1. Issue a card immediately — Use Create Card to issue a virtual card to this cardholder
  2. Verify identity (optional) — Use Initiate KYC Verification to let the cardholder verify themselves, or Submit KYC Documents to submit documents on their behalf
KYC verification is optional and does not block card issuance. You can issue cards to cardholders without completing KYC.

​
Error Responses

​
Duplicate Email (409)

{
  "success": false,
  "status": 409,
  "message": "A cardholder with this email already exists",
  "error": { "code": "CONFLICT" }
}

​
Duplicate External ID (409)

{
  "success": false,
  "status": 409,
  "message": "A cardholder with this externalId already exists",
  "error": { "code": "CONFLICT" }
}

​
Underage Cardholder (400)

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "dateOfBirth", "message": "Cardholder must be at least 18 years old." }
    ]
  }
}

​
Validation Error (400)

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "gender", "message": "The gender field is required." }
    ]
  }
}
Email addresses and external IDs must be unique within your business. If you try to create a cardholder with an email or externalId that already exists, you’ll receive a 409 Conflict error.
Use the externalId field to store your platform’s cardholder/user ID. This makes it easy to link FYATU cardholders to users in your own system.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Body

application/json
​
firstName
string
required

Cardholder's first name

Required string length: 1 - 100
​
lastName
string
required

Cardholder's last name

Required string length: 1 - 100
​
email
string<email>
required

Cardholder's email address (unique per app)

Maximum string length: 255
​
phone
string
required

Phone number with country code

Required string length: 6 - 20
​
dateOfBirth
string<date>
required

Date of birth (YYYY-MM-DD)

​
country
string
required

ISO 3166-1 alpha-2 country code

Required string length: 2
​
externalId
string

Your platform's cardholder ID (unique per app)

Maximum string length: 100
​
gender
enum<string>

Gender (optional)

Available options:
MALE,
FEMALE,
OTHER
​
address
string

Street address

Maximum string length: 255
​
city
string

City

Maximum string length: 100
​
state
string

State or province

Maximum string length: 100
​
zipCode
string

Postal/ZIP code

Maximum string length: 20
​
kyc
object

Optional KYC documents. When any KYC data is provided, kycStatus will be set to SUBMITTED. All fields are optional - use the Submit KYC endpoint for mandatory document submission.

Response

Cardholder created successfully

Response for create and update cardholder operations

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
​
data
object
​
meta
object