Create Cardholder

Create a cardholder

curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cardholders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "dateOfBirth": "1990-05-15",
  "nationality": "US",
  "address": {
    "address": "123 Main Street, Apt 4B",
    "city": "Newark",
    "country": "US",
    "state": "Delaware",
    "postalCode": "19701"
  },
  "phone": "+12025551234",
  "gender": "MALE",
  "kycDocument": {
    "documentType": "PASSPORT",
    "documentNumber": "AB123456",
    "issuingCountry": "US",
    "issuingDate": "2019-03-04",
    "expiryDate": "2029-03-03",
    "frontUrl": "https://storage.example.com/doc-front.jpg",
    "backUrl": null,
    "selfieUrl": "https://storage.example.com/selfie.jpg"
  },
  "externalId": "usr_123456",
  "metadata": {
    "plan": "premium"
  }
}
'

import requests

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

payload = {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "dateOfBirth": "1990-05-15",
    "nationality": "US",
    "address": {
        "address": "123 Main Street, Apt 4B",
        "city": "Newark",
        "country": "US",
        "state": "Delaware",
        "postalCode": "19701"
    },
    "phone": "+12025551234",
    "gender": "MALE",
    "kycDocument": {
        "documentType": "PASSPORT",
        "documentNumber": "AB123456",
        "issuingCountry": "US",
        "issuingDate": "2019-03-04",
        "expiryDate": "2029-03-03",
        "frontUrl": "https://storage.example.com/doc-front.jpg",
        "backUrl": None,
        "selfieUrl": "https://storage.example.com/selfie.jpg"
    },
    "externalId": "usr_123456",
    "metadata": { "plan": "premium" }
}
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({
    firstName: 'John',
    lastName: 'Smith',
    email: 'john.smith@example.com',
    dateOfBirth: '1990-05-15',
    nationality: 'US',
    address: {
      address: '123 Main Street, Apt 4B',
      city: 'Newark',
      country: 'US',
      state: 'Delaware',
      postalCode: '19701'
    },
    phone: '+12025551234',
    gender: 'MALE',
    kycDocument: {
      documentType: 'PASSPORT',
      documentNumber: 'AB123456',
      issuingCountry: 'US',
      issuingDate: '2019-03-04',
      expiryDate: '2029-03-03',
      frontUrl: 'https://storage.example.com/doc-front.jpg',
      backUrl: null,
      selfieUrl: 'https://storage.example.com/selfie.jpg'
    },
    externalId: 'usr_123456',
    metadata: {plan: 'premium'}
  })
};

fetch('https://api.fyatu.com/api/v3.20/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.20/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([
    'firstName' => 'John',
    'lastName' => 'Smith',
    'email' => 'john.smith@example.com',
    'dateOfBirth' => '1990-05-15',
    'nationality' => 'US',
    'address' => [
        'address' => '123 Main Street, Apt 4B',
        'city' => 'Newark',
        'country' => 'US',
        'state' => 'Delaware',
        'postalCode' => '19701'
    ],
    'phone' => '+12025551234',
    'gender' => 'MALE',
    'kycDocument' => [
        'documentType' => 'PASSPORT',
        'documentNumber' => 'AB123456',
        'issuingCountry' => 'US',
        'issuingDate' => '2019-03-04',
        'expiryDate' => '2029-03-03',
        'frontUrl' => 'https://storage.example.com/doc-front.jpg',
        'backUrl' => null,
        'selfieUrl' => 'https://storage.example.com/selfie.jpg'
    ],
    'externalId' => 'usr_123456',
    'metadata' => [
        'plan' => 'premium'
    ]
  ]),
  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.20/cardholders"

	payload := strings.NewReader("{\n  \"firstName\": \"John\",\n  \"lastName\": \"Smith\",\n  \"email\": \"john.smith@example.com\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"nationality\": \"US\",\n  \"address\": {\n    \"address\": \"123 Main Street, Apt 4B\",\n    \"city\": \"Newark\",\n    \"country\": \"US\",\n    \"state\": \"Delaware\",\n    \"postalCode\": \"19701\"\n  },\n  \"phone\": \"+12025551234\",\n  \"gender\": \"MALE\",\n  \"kycDocument\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB123456\",\n    \"issuingCountry\": \"US\",\n    \"issuingDate\": \"2019-03-04\",\n    \"expiryDate\": \"2029-03-03\",\n    \"frontUrl\": \"https://storage.example.com/doc-front.jpg\",\n    \"backUrl\": null,\n    \"selfieUrl\": \"https://storage.example.com/selfie.jpg\"\n  },\n  \"externalId\": \"usr_123456\",\n  \"metadata\": {\n    \"plan\": \"premium\"\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.20/cardholders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"John\",\n  \"lastName\": \"Smith\",\n  \"email\": \"john.smith@example.com\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"nationality\": \"US\",\n  \"address\": {\n    \"address\": \"123 Main Street, Apt 4B\",\n    \"city\": \"Newark\",\n    \"country\": \"US\",\n    \"state\": \"Delaware\",\n    \"postalCode\": \"19701\"\n  },\n  \"phone\": \"+12025551234\",\n  \"gender\": \"MALE\",\n  \"kycDocument\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB123456\",\n    \"issuingCountry\": \"US\",\n    \"issuingDate\": \"2019-03-04\",\n    \"expiryDate\": \"2029-03-03\",\n    \"frontUrl\": \"https://storage.example.com/doc-front.jpg\",\n    \"backUrl\": null,\n    \"selfieUrl\": \"https://storage.example.com/selfie.jpg\"\n  },\n  \"externalId\": \"usr_123456\",\n  \"metadata\": {\n    \"plan\": \"premium\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fyatu.com/api/v3.20/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  \"firstName\": \"John\",\n  \"lastName\": \"Smith\",\n  \"email\": \"john.smith@example.com\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"nationality\": \"US\",\n  \"address\": {\n    \"address\": \"123 Main Street, Apt 4B\",\n    \"city\": \"Newark\",\n    \"country\": \"US\",\n    \"state\": \"Delaware\",\n    \"postalCode\": \"19701\"\n  },\n  \"phone\": \"+12025551234\",\n  \"gender\": \"MALE\",\n  \"kycDocument\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB123456\",\n    \"issuingCountry\": \"US\",\n    \"issuingDate\": \"2019-03-04\",\n    \"expiryDate\": \"2029-03-03\",\n    \"frontUrl\": \"https://storage.example.com/doc-front.jpg\",\n    \"backUrl\": null,\n    \"selfieUrl\": \"https://storage.example.com/selfie.jpg\"\n  },\n  \"externalId\": \"usr_123456\",\n  \"metadata\": {\n    \"plan\": \"premium\"\n  }\n}"

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

{
  "success": true,
  "status": 201,
  "message": "Cardholder created",
  "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": "PENDING",
    "kycVerifiedAt": null,
    "totalCards": 0,
    "suspendedAt": null,
    "createdAt": "2026-05-01T09:00:00Z",
    "updatedAt": "2026-05-01T09:00:00Z"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-01T09:00:00Z"
  }
}

POST

cardholders

Create a cardholder

curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cardholders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "dateOfBirth": "1990-05-15",
  "nationality": "US",
  "address": {
    "address": "123 Main Street, Apt 4B",
    "city": "Newark",
    "country": "US",
    "state": "Delaware",
    "postalCode": "19701"
  },
  "phone": "+12025551234",
  "gender": "MALE",
  "kycDocument": {
    "documentType": "PASSPORT",
    "documentNumber": "AB123456",
    "issuingCountry": "US",
    "issuingDate": "2019-03-04",
    "expiryDate": "2029-03-03",
    "frontUrl": "https://storage.example.com/doc-front.jpg",
    "backUrl": null,
    "selfieUrl": "https://storage.example.com/selfie.jpg"
  },
  "externalId": "usr_123456",
  "metadata": {
    "plan": "premium"
  }
}
'

import requests

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

payload = {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "dateOfBirth": "1990-05-15",
    "nationality": "US",
    "address": {
        "address": "123 Main Street, Apt 4B",
        "city": "Newark",
        "country": "US",
        "state": "Delaware",
        "postalCode": "19701"
    },
    "phone": "+12025551234",
    "gender": "MALE",
    "kycDocument": {
        "documentType": "PASSPORT",
        "documentNumber": "AB123456",
        "issuingCountry": "US",
        "issuingDate": "2019-03-04",
        "expiryDate": "2029-03-03",
        "frontUrl": "https://storage.example.com/doc-front.jpg",
        "backUrl": None,
        "selfieUrl": "https://storage.example.com/selfie.jpg"
    },
    "externalId": "usr_123456",
    "metadata": { "plan": "premium" }
}
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({
    firstName: 'John',
    lastName: 'Smith',
    email: 'john.smith@example.com',
    dateOfBirth: '1990-05-15',
    nationality: 'US',
    address: {
      address: '123 Main Street, Apt 4B',
      city: 'Newark',
      country: 'US',
      state: 'Delaware',
      postalCode: '19701'
    },
    phone: '+12025551234',
    gender: 'MALE',
    kycDocument: {
      documentType: 'PASSPORT',
      documentNumber: 'AB123456',
      issuingCountry: 'US',
      issuingDate: '2019-03-04',
      expiryDate: '2029-03-03',
      frontUrl: 'https://storage.example.com/doc-front.jpg',
      backUrl: null,
      selfieUrl: 'https://storage.example.com/selfie.jpg'
    },
    externalId: 'usr_123456',
    metadata: {plan: 'premium'}
  })
};

fetch('https://api.fyatu.com/api/v3.20/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.20/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([
    'firstName' => 'John',
    'lastName' => 'Smith',
    'email' => 'john.smith@example.com',
    'dateOfBirth' => '1990-05-15',
    'nationality' => 'US',
    'address' => [
        'address' => '123 Main Street, Apt 4B',
        'city' => 'Newark',
        'country' => 'US',
        'state' => 'Delaware',
        'postalCode' => '19701'
    ],
    'phone' => '+12025551234',
    'gender' => 'MALE',
    'kycDocument' => [
        'documentType' => 'PASSPORT',
        'documentNumber' => 'AB123456',
        'issuingCountry' => 'US',
        'issuingDate' => '2019-03-04',
        'expiryDate' => '2029-03-03',
        'frontUrl' => 'https://storage.example.com/doc-front.jpg',
        'backUrl' => null,
        'selfieUrl' => 'https://storage.example.com/selfie.jpg'
    ],
    'externalId' => 'usr_123456',
    'metadata' => [
        'plan' => 'premium'
    ]
  ]),
  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.20/cardholders"

	payload := strings.NewReader("{\n  \"firstName\": \"John\",\n  \"lastName\": \"Smith\",\n  \"email\": \"john.smith@example.com\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"nationality\": \"US\",\n  \"address\": {\n    \"address\": \"123 Main Street, Apt 4B\",\n    \"city\": \"Newark\",\n    \"country\": \"US\",\n    \"state\": \"Delaware\",\n    \"postalCode\": \"19701\"\n  },\n  \"phone\": \"+12025551234\",\n  \"gender\": \"MALE\",\n  \"kycDocument\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB123456\",\n    \"issuingCountry\": \"US\",\n    \"issuingDate\": \"2019-03-04\",\n    \"expiryDate\": \"2029-03-03\",\n    \"frontUrl\": \"https://storage.example.com/doc-front.jpg\",\n    \"backUrl\": null,\n    \"selfieUrl\": \"https://storage.example.com/selfie.jpg\"\n  },\n  \"externalId\": \"usr_123456\",\n  \"metadata\": {\n    \"plan\": \"premium\"\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.20/cardholders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"John\",\n  \"lastName\": \"Smith\",\n  \"email\": \"john.smith@example.com\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"nationality\": \"US\",\n  \"address\": {\n    \"address\": \"123 Main Street, Apt 4B\",\n    \"city\": \"Newark\",\n    \"country\": \"US\",\n    \"state\": \"Delaware\",\n    \"postalCode\": \"19701\"\n  },\n  \"phone\": \"+12025551234\",\n  \"gender\": \"MALE\",\n  \"kycDocument\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB123456\",\n    \"issuingCountry\": \"US\",\n    \"issuingDate\": \"2019-03-04\",\n    \"expiryDate\": \"2029-03-03\",\n    \"frontUrl\": \"https://storage.example.com/doc-front.jpg\",\n    \"backUrl\": null,\n    \"selfieUrl\": \"https://storage.example.com/selfie.jpg\"\n  },\n  \"externalId\": \"usr_123456\",\n  \"metadata\": {\n    \"plan\": \"premium\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fyatu.com/api/v3.20/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  \"firstName\": \"John\",\n  \"lastName\": \"Smith\",\n  \"email\": \"john.smith@example.com\",\n  \"dateOfBirth\": \"1990-05-15\",\n  \"nationality\": \"US\",\n  \"address\": {\n    \"address\": \"123 Main Street, Apt 4B\",\n    \"city\": \"Newark\",\n    \"country\": \"US\",\n    \"state\": \"Delaware\",\n    \"postalCode\": \"19701\"\n  },\n  \"phone\": \"+12025551234\",\n  \"gender\": \"MALE\",\n  \"kycDocument\": {\n    \"documentType\": \"PASSPORT\",\n    \"documentNumber\": \"AB123456\",\n    \"issuingCountry\": \"US\",\n    \"issuingDate\": \"2019-03-04\",\n    \"expiryDate\": \"2029-03-03\",\n    \"frontUrl\": \"https://storage.example.com/doc-front.jpg\",\n    \"backUrl\": null,\n    \"selfieUrl\": \"https://storage.example.com/selfie.jpg\"\n  },\n  \"externalId\": \"usr_123456\",\n  \"metadata\": {\n    \"plan\": \"premium\"\n  }\n}"

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

{
  "success": true,
  "status": 201,
  "message": "Cardholder created",
  "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": "PENDING",
    "kycVerifiedAt": null,
    "totalCards": 0,
    "suspendedAt": null,
    "createdAt": "2026-05-01T09:00:00Z",
    "updatedAt": "2026-05-01T09:00:00Z"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-01T09:00:00Z"
  }
}

Overview

Create a cardholder profile for an end user. Cardholders are created with kycStatus: WAIVED — cards can be issued to them immediately, without waiting for identity verification. If your compliance requirements demand full identity verification, call POST /cardholders/{id}/kyc after creation to move the cardholder to PENDING and then APPROVED.

Required Fields

Field	Type	Constraint
`firstName`	string	Legal first name
`lastName`	string	Legal last name
`email`	string	Valid email, unique within your environment
`dateOfBirth`	string	`YYYY-MM-DD` format, cardholder must be 18+
`nationality`	string	ISO 3166-1 alpha-2 (e.g. `US`)
`address.address`	string	Full street address (line 1 and optional line 2 combined)
`address.city`	string	City
`address.country`	string	ISO 3166-1 alpha-2

Optional Fields

Field	Type	Constraint
`gender`	string	`MALE` or `FEMALE` (`M` / `F` also accepted). Required for verification on programmes that need a verified cardholder — an identity check cannot be run without it. Omit it and the cardholder can still be issued cards on programmes that require no verification.
`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 forwarded to the card network on card creation so they count as separate holders. Unlike the identity fields below, `middleName` stays editable after KYC approval.
`phone`	string	Phone number in E.164 format
`externalId`	string	Your platform’s cardholder ID
`metadata`	object	Arbitrary flat JSON object of custom key-value pairs

KYC-Locked Fields

After KYC approval, these fields become immutable: firstName, lastName, email, dateOfBirth, nationality, address. Attempting to change them returns 409 KYC_FIELD_LOCKED. middleName is intentionally not locked and remains editable after approval.

KYC Document

The optional kycDocument object supplies the identity document. It is not KYC-locked and can be updated via PATCH at any time. Supply it when the cardholder needs to be verified — that is, when you intend to issue on a programme whose BINs require a verified cardholder. Without it the cardholder can still be issued cards on programmes that require no verification. GET /cardholders/{id} tells you which programmes are open to a given cardholder, and why.

Field	Type	Description
`documentType`	string	`PASSPORT`, `NATIONAL_ID`, `DRIVERS_LICENSE`, or `RESIDENCE_PERMIT`
`documentNumber`	string	Document number as printed
`issuingCountry`	string	ISO 3166-1 alpha-2
`issuingDate`	string	Date of issue, formatted `1994-12-31`
`expiryDate`	string	Date of expiry, formatted `1994-12-31`. Must be in the future and after `issuingDate`
`frontUrl`	string	HTTPS URL of the document front image
`backUrl`	string	HTTPS URL of the document back image (not required for passports)
`selfieUrl`	string	HTTPS URL of the cardholder selfie

A document is verified as a whole, so it is accepted as a whole. Supply every field, or none — a partial document returns 422 KYC_DOCUMENT_INVALID rather than being stored and quietly ignored, which would leave you believing verification was under way when it was not.frontUrl and selfieUrl must be given together. Images are copied to our own storage on receipt, so a link that later expires does not interrupt a review.

Example

curl -X POST https://api.fyatu.com/api/v3.20/cardholders \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
      "state":      "Delaware",
      "postalCode": "19701",
      "country":    "US"
    },
    "kycDocument": {
      "documentType":   "PASSPORT",
      "issuingDate":    "2019-03-04",
      "expiryDate":     "2029-03-03",
      "documentNumber": "AB123456",
      "issuingCountry": "US",
      "frontUrl":       "https://storage.example.com/doc-front.jpg",
      "selfieUrl":      "https://storage.example.com/selfie.jpg"
    },
    "externalId": "usr_123456",
    "metadata":   { "plan": "premium", "region": "us-east" }
  }'

const resp = await fetch('https://api.fyatu.com/api/v3.20/cardholders', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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',
      state:      'Delaware',
      postalCode: '19701',
      country:    'US'
    },
    kycDocument: {
      documentType:   'PASSPORT',
      documentNumber: 'AB123456',
      issuingCountry: 'US',
      frontUrl:       'https://storage.example.com/doc-front.jpg',
      selfieUrl:      'https://storage.example.com/selfie.jpg'
    },
    externalId: 'usr_123456',
    metadata:   { plan: 'premium', region: 'us-east' }
  })
});

const body = await resp.json();
const cardholder = body.data;
console.log('Cardholder:', cardholder.cardholderId, '| KYC:', cardholder.kycStatus);

import os, requests

resp = requests.post(
    'https://api.fyatu.com/api/v3.20/cardholders',
    headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
    json={
        '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',
            'postalCode': '19701',
            'country':    'US'
        },
        'kycDocument': {
            'documentType':   'PASSPORT',
            'documentNumber': 'AB123456',
            'issuingCountry': 'US',
            'frontUrl':       'https://storage.example.com/doc-front.jpg',
            'selfieUrl':      'https://storage.example.com/selfie.jpg'
        },
        'externalId': 'usr_123456'
    }
)
body = resp.json()
cardholder = body['data']
print(cardholder['cardholderId'], cardholder['kycStatus'])

Success Response (201)

{
  "success": true,
  "status": 201,
  "message": "Cardholder created",
  "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", "region": "us-east" },
    "status":        "ACTIVE",
    "kycStatus":     "WAIVED",
    "kycVerifiedAt": null,
    "totalCards":    0,
    "suspendedAt":   null,
    "createdAt":     "2026-05-22T10:00:00Z",
    "updatedAt":     "2026-05-22T10:00:00Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

Conditional fields — present only in specific states:

Field	Condition
`kycRejectionReason`	Only when `kycStatus` is `REJECTED`
`terminatedAt`	Only when `status` is `TERMINATED`

Webhook

A CARDHOLDER_CREATED event fires after successful creation:

{
  "event":      "CARDHOLDER_CREATED",
  "eventId":    "evt_01HXY123456ABCDEF",
  "businessId": "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":  "2026-05-22T10:00:00Z",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "firstName":    "John",
    "lastName":     "Smith",
    "email":        "john.smith@example.com",
    "status":       "ACTIVE",
    "kycStatus":    "WAIVED",
    "externalId":   "usr_123456"
  }
}

If you later run full verification with POST /cardholders/{id}/kyc, a CARDHOLDER_KYC_APPROVED or CARDHOLDER_KYC_REJECTED event fires when the provider responds.

Error Codes

Code	HTTP	Cause
`INVALID_BODY`	400	Request body is not valid JSON
`VALIDATION_ERROR`	422	Missing or invalid fields (e.g. bad email, missing `address.city`)
`CARDHOLDER_UNDER_AGE`	422	`dateOfBirth` indicates cardholder is under 18
`CARDHOLDER_EMAIL_EXISTS`	409	Email already registered in this environment
`KYC_DOCUMENT_INVALID`	422	`kycDocument` is incomplete, a date is not formatted `1994-12-31`, the document has expired, or an image URL is not https
`CARDHOLDER_INVALID_GENDER`	422	`gender` is not `MALE` or `FEMALE`
`INSUFFICIENT_SCOPE`	403	Key lacks `cardholders:write` scope
`INTERNAL_ERROR`	500	Server error

Authorizations

Authorization

string

header

required

API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

Body

application/json

firstName

string

required

Example:

"John"

lastName

string

required

Example:

"Smith"

string<email>

required

Example:

"john.smith@example.com"

dateOfBirth

string<date>

required

YYYY-MM-DD â€” must be 18+

Example:

"1990-05-15"

nationality

string

required

ISO 3166-1 alpha-2

Example:

"US"

address

object

required

Show child attributes

phone

string

Example:

"+12025551234"

gender

enum<string>

Cardholder gender. Required for verification on programmes that need a verified cardholder — an identity check cannot be run without it.

Available options:

MALE,

FEMALE,

M,

F

Example:

"MALE"

kycDocument

object

Identity document details for verification. Optional on create; patchable at any time and not locked after approval. Accepted as a whole — a partial document is refused rather than stored and ignored. Images are copied to our own storage on receipt.

Show child attributes

externalId

string

Example:

"usr_123456"

metadata

object

Example:

{ "plan": "premium" }

Response

Cardholder created

success

boolean

Example:

true

status

integer

Example:

200

message

string

Example:

"Cardholder retrieved"

data

object

Show child attributes

Account

Products

Cardholders

Cards

Webhooks

Overview

Required Fields

Optional Fields

KYC-Locked Fields

KYC Document

Example

Success Response (201)

Webhook

Error Codes

Authorizations

Body

Response

​Overview

​Required Fields

​Optional Fields

​KYC-Locked Fields

​KYC Document

​Example

​Success Response (201)

​Webhook

​Error Codes

Authorizations

Body

Response

Overview

Required Fields

Optional Fields

KYC-Locked Fields

KYC Document

Example

Success Response (201)

Webhook

Error Codes