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

import requests

url = "https://api.fyatu.com/api/v3/cardholders"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.fyatu.com/api/v3/cardholders', 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://api.fyatu.com/api/v3/cardholders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fyatu.com/api/v3/cardholders"

	payload := strings.NewReader("{\n  \"externalId\": \"EXT-0001\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Example\",\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+15550001234\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"gender\": \"MALE\",\n  \"address\": \"123 Main Street, Apt 4B\",\n  \"city\": \"Newark\",\n  \"state\": \"Delaware\",\n  \"country\": \"US\",\n  \"zipCode\": \"000000\",\n  \"kyc\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB1234567\",\n    \"idFrontUrl\": \"https://storage.example.com/docs/passport_front.jpg\",\n    \"idBackUrl\": \"https://storage.example.com/docs/passport_back.jpg\",\n    \"idSelfieUrl\": \"https://storage.example.com/docs/selfie.jpg\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3/cardholders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalId\": \"EXT-0001\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Example\",\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+15550001234\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"gender\": \"MALE\",\n  \"address\": \"123 Main Street, Apt 4B\",\n  \"city\": \"Newark\",\n  \"state\": \"Delaware\",\n  \"country\": \"US\",\n  \"zipCode\": \"000000\",\n  \"kyc\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB1234567\",\n    \"idFrontUrl\": \"https://storage.example.com/docs/passport_front.jpg\",\n    \"idBackUrl\": \"https://storage.example.com/docs/passport_back.jpg\",\n    \"idSelfieUrl\": \"https://storage.example.com/docs/selfie.jpg\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fyatu.com/api/v3/cardholders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalId\": \"EXT-0001\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Example\",\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+15550001234\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"gender\": \"MALE\",\n  \"address\": \"123 Main Street, Apt 4B\",\n  \"city\": \"Newark\",\n  \"state\": \"Delaware\",\n  \"country\": \"US\",\n  \"zipCode\": \"000000\",\n  \"kyc\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB1234567\",\n    \"idFrontUrl\": \"https://storage.example.com/docs/passport_front.jpg\",\n    \"idBackUrl\": \"https://storage.example.com/docs/passport_back.jpg\",\n    \"idSelfieUrl\": \"https://storage.example.com/docs/selfie.jpg\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "currency",
        "message": "Currency is required"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

{
  "success": false,
  "status": 401,
  "message": "Unable to identify business",
  "error": {
    "code": "AUTH_TOKEN_INVALID"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

{
  "success": false,
  "status": 401,
  "message": "Invalid credentials",
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS",
    "details": [
      {
        "field": "appId",
        "message": "AppId is required"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

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

import requests

url = "https://api.fyatu.com/api/v3/cardholders"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.fyatu.com/api/v3/cardholders', 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://api.fyatu.com/api/v3/cardholders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fyatu.com/api/v3/cardholders"

	payload := strings.NewReader("{\n  \"externalId\": \"EXT-0001\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Example\",\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+15550001234\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"gender\": \"MALE\",\n  \"address\": \"123 Main Street, Apt 4B\",\n  \"city\": \"Newark\",\n  \"state\": \"Delaware\",\n  \"country\": \"US\",\n  \"zipCode\": \"000000\",\n  \"kyc\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB1234567\",\n    \"idFrontUrl\": \"https://storage.example.com/docs/passport_front.jpg\",\n    \"idBackUrl\": \"https://storage.example.com/docs/passport_back.jpg\",\n    \"idSelfieUrl\": \"https://storage.example.com/docs/selfie.jpg\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3/cardholders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalId\": \"EXT-0001\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Example\",\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+15550001234\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"gender\": \"MALE\",\n  \"address\": \"123 Main Street, Apt 4B\",\n  \"city\": \"Newark\",\n  \"state\": \"Delaware\",\n  \"country\": \"US\",\n  \"zipCode\": \"000000\",\n  \"kyc\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB1234567\",\n    \"idFrontUrl\": \"https://storage.example.com/docs/passport_front.jpg\",\n    \"idBackUrl\": \"https://storage.example.com/docs/passport_back.jpg\",\n    \"idSelfieUrl\": \"https://storage.example.com/docs/selfie.jpg\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fyatu.com/api/v3/cardholders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalId\": \"EXT-0001\",\n  \"firstName\": \"Alice\",\n  \"lastName\": \"Example\",\n  \"email\": \"alice@example.com\",\n  \"phone\": \"+15550001234\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"gender\": \"MALE\",\n  \"address\": \"123 Main Street, Apt 4B\",\n  \"city\": \"Newark\",\n  \"state\": \"Delaware\",\n  \"country\": \"US\",\n  \"zipCode\": \"000000\",\n  \"kyc\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB1234567\",\n    \"idFrontUrl\": \"https://storage.example.com/docs/passport_front.jpg\",\n    \"idBackUrl\": \"https://storage.example.com/docs/passport_back.jpg\",\n    \"idSelfieUrl\": \"https://storage.example.com/docs/selfie.jpg\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "currency",
        "message": "Currency is required"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

{
  "success": false,
  "status": 401,
  "message": "Unable to identify business",
  "error": {
    "code": "AUTH_TOKEN_INVALID"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

{
  "success": false,
  "status": 401,
  "message": "Invalid credentials",
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS",
    "details": [
      {
        "field": "appId",
        "message": "AppId is required"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

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

Field	Type	Description
`firstName`	string	Cardholder’s first name (1-100 chars)
`lastName`	string	Cardholder’s last name (1-100 chars)
`email`	string	Email address (unique per business)
`phone`	string	Phone number in E.164 format (e.g. `+15550001234`)
`dateOfBirth`	string	Date of birth (`YYYY-MM-DD`, must be 18+ years old)
`gender`	string	Gender (`MALE` or `FEMALE`)
`country`	string	ISO 3166-1 alpha-2 country code (e.g. `US`)

Address Fields

Field	Type	Required	Description
`address`	string	Yes	Street address (max 255 chars)
`city`	string	Yes	City (max 100 chars)
`state`	string	Yes	State or province (max 100 chars)
`zipCode`	string	Yes	Postal/ZIP code (max 20 chars)

Optional Fields

Field	Type	Description
`middleName`	string	Optional middle name (max 15 chars). Card issuers cap the number of active cards per identical first + last name, so set a `middleName` to distinguish two cardholders who share the same first and last name — when present it is sent to the card network on card creation so they count as separate holders. Unlike `firstName`/`lastName`, `middleName` stays editable after KYC approval.
`externalId`	string	Your platform’s cardholder ID (unique per business, max 100 chars)
`metadata`	object	Arbitrary key-value pairs to store custom data about the cardholder

KYC Object (Shared KYC — Enabled Businesses Only)

Cardholder KYC behaviour depends on your business’s KYC mode:

Managed (default) — the new cardholder starts at UNSUBMITTED; verify them afterwards (self-service session or document submission).
Shared — you may include a kyc object here to submit the documents you already hold. The cardholder is set to PENDING and FYATU runs a background verification on them; a cardholder.kyc_approved webhook fires once verified.
Minimal (No-KYC) — the cardholder is created as WAIVED and can be issued a card immediately; no kyc object is needed (if sent, it is accepted but not required).

If your business does not have Shared KYC enabled, the kyc object is silently ignored regardless of what is sent.

Field	Type	Required	Description
`kyc.idFrontUrl`	string	Yes	URL to the front image of the ID document
`kyc.selfieUrl`	string	Yes	URL to a selfie photo of the cardholder
`kyc.idBackUrl`	string	No	URL to the back image of the ID document
`kyc.documentType`	string	No	`PASSPORT`, `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";

const 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',
  },
};

const response = await fetch('https://api.fyatu.com/api/v3/cardholders', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

const result = await response.json();
console.log('Created cardholder:', result.data.id);

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:

Verify identity — Use Initiate KYC Verification to let the cardholder verify themselves, or Submit KYC Documents to submit documents on their behalf. Required under Managed and Shared; not needed under Minimal.
Issue a card — Use Create Card. Immediate under Minimal (WAIVED); under Managed / Shared the cardholder must first reach ACCEPTED.

Whether KYC is required before issuance depends on your KYC mode: under Managed and Shared a cardholder must reach ACCEPTED before a card can be issued; under Minimal (No-KYC) cardholders are created WAIVED and can be issued a card immediately.

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

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.

Show child attributes

Response

Cardholder created successfully

Response for create and update cardholder operations

success

boolean

Example:

true

status

integer

Example:

201

message

string

data

object

Show child attributes

Overview

Authentication

Account

Collections

Payouts

Cardholders

Cards

Create Cardholder

Overview

Required Fields

Address Fields

Optional Fields

KYC Object (Shared KYC — Enabled Businesses Only)

Metadata Object (Optional)

Example Usage

Example Response

Next Steps

Error Responses

Duplicate Email (409)

Duplicate External ID (409)

Underage Cardholder (400)

Validation Error (400)

Authorizations

Body

Response

​Overview

​Required Fields

​Address Fields

​Optional Fields

​KYC Object (Shared KYC — Enabled Businesses Only)

​Metadata Object (Optional)

​Example Usage

​Example Response

​Next Steps

​Error Responses

​Duplicate Email (409)

​Duplicate External ID (409)

​Underage Cardholder (400)

​Validation Error (400)

Authorizations

Body

Response

Overview

Required Fields

Address Fields

Optional Fields

KYC Object (Shared KYC — Enabled Businesses Only)

Metadata Object (Optional)

Example Usage

Example Response

Next Steps

Error Responses

Duplicate Email (409)

Duplicate External ID (409)

Underage Cardholder (400)

Validation Error (400)