Skip to main content
POST
/
cardholders
Create Cardholder
curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cardholders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "user_12345",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+15551234567",
  "dateOfBirth": "1990-06-15",
  "gender": "F",
  "address": {
    "line1": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zipCode": "10001"
  },
  "document": {
    "type": "PASSPORT",
    "number": "AB123456"
  },
  "metadata": {
    "tier": "premium"
  }
}
'
{
  "success": true,
  "status": 123,
  "data": {
    "id": "<string>",
    "externalId": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "dateOfBirth": "<string>",
    "gender": "<string>",
    "address": {},
    "document": {},
    "kyc": {
      "status": "UNSUBMITTED",
      "sessionUrl": "<string>"
    },
    "status": "ACTIVE",
    "cardsCount": 123,
    "metadata": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_9f3e2a1b4c5d67e8",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

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 cardholder profile for an end user. Cardholders must be created before cards can be issued to them. KYC is not required to create a cardholder, but must be approved before card issuance.

​
Prerequisites

  • Your business must have an ACTIVE status
  • externalId must be unique within your business

​
Request Body

FieldTypeRequiredDescription
externalIdstringYesYour internal user ID — must be unique within your business
firstNamestringYesLegal first name
lastNamestringYesLegal last name
emailstringYesEmail address
phonestringYesPhone number in E.164 format (+12025551234)
dateOfBirthstringYesDate of birth (YYYY-MM-DD)
genderstringYesMALE, FEMALE, or OTHER
addressstringYesStreet address
citystringYesCity
statestringYesState or region
countrystringYesCountry code (ISO 3166-1 alpha-2, e.g., US)
zipCodestringYesPostal / ZIP code

​
Example

curl -X POST "https://api.fyatu.com/api/v3.20/cardholders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "USR-12345",
    "firstName": "John",
    "lastName": "Smith",
    "email": "johnsmith@example.com",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "address": "123 Main Street, Apt 4B",
    "city": "Newark",
    "state": "Delaware",
    "country": "US",
    "zipCode": "000000"
  }'

​
Error Codes

CodeDescription
VALIDATION_ERRORMissing or invalid fields
DUPLICATE_EXTERNAL_IDA cardholder with this externalId already exists
After creating a cardholder, initiate KYC with POST /cardholders/{id}/kyc/session. Cards can only be issued once kycStatus is APPROVED.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from POST /auth/token

Body

application/json
​
firstName
string
required
Example:

"Jane"

​
lastName
string
required
Example:

"Doe"

​
email
string<email>
required
Example:

"jane.doe@example.com"

​
phone
string
required

E.164 format

Example:

"+15551234567"

​
dateOfBirth
string<date>
required

Must be 18+ years old

Example:

"1990-06-15"

​
gender
enum<string>
required
Available options:
M,
F
​
externalId
string

Your internal user ID — must be unique per business

Example:

"user_12345"

​
address
object
​
document
object
​
metadata
object

Key-value pairs stored against the cardholder

Response

Cardholder created

​
success
boolean
​
status
integer
​
data
object
​
meta
object