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": "F45786646",
  "firstName": "John",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+12025551234",
  "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": "F45786646",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "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"
  }
}

​
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 app)
phonestringPhone number in E.164 format (e.g. +12025551234)
dateOfBirthstringDate of birth (YYYY-MM-DD)
genderstringGender (MALE or FEMALE)
countrystringISO 3166-1 alpha-2 country code (e.g. US)

​
Optional Fields

FieldTypeDescription
externalIdstringYour platform’s cardholder ID (unique per app, max 100 chars)
addressstringStreet address (max 255 chars)
citystringCity (max 100 chars)
statestringState or province (max 100 chars)
zipCodestringPostal/ZIP code (max 20 chars)

​
Example Usage

<?php
$data = [
    'externalId' => 'F45786646',
    'firstName' => 'John',
    'lastName' => 'Smith',
    'email' => '[email protected]',
    'phone' => '+12025551234',
    'dateOfBirth' => '1990-05-15',
    'gender' => 'MALE',
    'address' => '123 Main Street, Apt 4B',
    'city' => 'Newark',
    'state' => 'Delaware',
    'country' => 'US',
    'zipCode' => '000000'
];

$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": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "externalId": "F45786646",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "address": {
      "line1": "123 Main Street, Apt 4B",
      "city": "Newark",
      "state": "Delaware",
      "country": "US",
      "zipCode": "000000"
    },
    "status": "ACTIVE",
    "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 verify the cardholder’s identity
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" }
}

​
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 application. 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