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"
    },
    "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 optionally include KYC documents in the request body - if provided, the kycStatus will be set to PENDING, otherwise it defaults to UNSUBMITTED.

​
Required Fields

FieldTypeDescription
firstNamestringCardholder’s first name (1-100 chars)
lastNamestringCardholder’s last name (1-100 chars)
emailstringEmail address (unique per app)
phonestringPhone number with country code
dateOfBirthstringDate of birth (YYYY-MM-DD)
countrystringISO 3166-1 alpha-2 country code (2 chars)

​
Optional Fields

FieldTypeDescription
externalIdstringYour platform’s cardholder ID (unique per app)
genderstringGender (MALE, FEMALE, OTHER)
addressstringStreet address
citystringCity
statestringState or province
zipCodestringPostal/ZIP code
kycobjectKYC documents (optional, see below)

​
KYC Object (Optional)

Include KYC documents at creation time to streamline onboarding. When any KYC data is provided, kycStatus will be set to PENDING. All fields within the kyc object are optional - use the Submit KYC endpoint for mandatory document submission.
FieldTypeRequiredDescription
documentTypestringNoPASSPORT, NATIONAL_ID, or DRIVER_LICENSE
documentNumberstringNoDocument identification number
idFrontUrlstringNoURL to the front image of the ID document
idBackUrlstringNoURL to the back image (recommended for ID cards)
idSelfieUrlstringNoURL to a selfie photo holding the ID document

​
Example Usage

​
Basic (without KYC)

<?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";
// kycStatus will be "UNSUBMITTED"

​
With KYC Documents

<?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',
    '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'
    ]
];

$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";
// kycStatus will be "PENDING"

​
Example Response

​
Without KYC

{
  "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",
    "kycStatus": "UNSUBMITTED",
    "createdAt": "2026-01-15T21:31:39+00:00"
  },
  "meta": {
    "requestId": "req_2f7fb4227a1007418773122f",
    "timestamp": "2026-01-15T21:31:39+00:00"
  }
}

​
With KYC

{
  "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",
    "kycStatus": "PENDING",
    "createdAt": "2026-01-15T21:31:39+00:00"
  },
  "meta": {
    "requestId": "req_2f7fb4227a1007418773122f",
    "timestamp": "2026-01-15T21:31:39+00:00"
  }
}

​
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" }
}

​
Invalid KYC Data (400)

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "kyc.idFrontUrl", "message": "The kyc.idFrontUrl field must contain a valid URL." }
    ]
  }
}
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.
Including KYC documents during creation streamlines the onboarding process. The cardholder will be created with kycStatus: "PENDING" and verification will be processed automatically.

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 PENDING. 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