Skip to main content
PATCH
/
cardholders
/
{id}
Update Cardholder
curl --request PATCH \
  --url https://api.fyatu.com/api/v3/cardholders/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone": "+1987654321",
  "address": "456 Oak Avenue",
  "city": "Los Angeles",
  "state": "CA"
}
'
{
  "success": true,
  "status": 200,
  "message": "Cardholder updated successfully",
  "data": {
    "id": "CH1a2b3c4d5e6f",
    "externalId": "USR-78945",
    "firstName": "James",
    "lastName": "Wilson",
    "email": "james.wilson@example.com",
    "phone": "+19876543210",
    "dateOfBirth": "1988-03-22",
    "gender": "MALE",
    "address": {
      "line1": "456 Oak Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "zipCode": "90001"
    },
    "document": {
      "type": "PASSPORT",
      "number": "XY7891234"
    },
    "kyc": {
      "status": "ACCEPTED",
      "idFrontUrl": null,
      "idBackUrl": null,
      "selfieUrl": null
    },
    "metadata": null,
    "status": "ACTIVE",
    "cardsCount": 2,
    "createdAt": "2026-01-10T14:30:00Z",
    "updatedAt": "2026-01-17T11:00:00Z"
  },
  "meta": {
    "requestId": "req_e5f6g7h8i9j0",
    "timestamp": "2026-01-17T11:00:00Z"
  }
}

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

Update cardholder information. Only the fields you provide will be updated. Note that the email address cannot be changed after creation.

​
Path Parameters

ParameterTypeDescription
idstringUnique cardholder identifier

​
Updatable Fields

FieldTypeDescription
firstNamestringFirst name
lastNamestringLast name
phonestringPhone number in E.164 format
dateOfBirthstringDate of birth (YYYY-MM-DD, must be 18+)
genderstringGender (MALE or FEMALE)
addressstringStreet address
citystringCity
statestringState or province
countrystringISO country code (2 chars)
zipCodestringPostal/ZIP code
documentTypestringDocument type (PASSPORT, NATIONAL_ID, DRIVER_LICENSE)
documentNumberstringDocument number
externalIdstringYour system’s identifier
statusstringStatus (ACTIVE, INACTIVE, SUSPENDED)
metadataobjectCustom key-value data (merge semantics, see below)

​
Metadata (Merge Semantics)

The metadata field uses merge semantics on update:
  • Add a key: include the key with a value
  • Update a key: include the key with a new value
  • Delete a key: set the key to null or ""
  • Keys you don’t include are left unchanged
// Existing metadata: { "department": "Engineering", "tier": "VIP" }

// This request:
{ "metadata": { "tier": "Premium", "cost_center": "CC-500", "department": "" } }

// Results in: { "tier": "Premium", "cost_center": "CC-500" }
// "tier" was updated, "cost_center" was added, "department" was deleted
To clear all metadata, pass an empty object with every key set to null.

​
Example Usage

<?php
$cardholderId = 'CH1a2b3c4d5e6f';

$data = [
    'phone' => '+1987654321',
    'address' => '456 Oak Avenue',
    'city' => 'Los Angeles',
    'state' => 'CA',
    'metadata' => [
        'department' => 'Sales',        // update existing key
        'badge_number' => 'B-789',      // add new key
    ],
];

$response = file_get_contents(
    "https://api.fyatu.com/api/v3/cardholders/{$cardholderId}",
    false,
    stream_context_create([
        'http' => [
            'method' => 'PATCH',
            'header' => [
                'Authorization: Bearer ' . $accessToken,
                'Content-Type: application/json'
            ],
            'content' => json_encode($data)
        ]
    ])
);

$result = json_decode($response, true);
echo "Updated cardholder: " . $result['data']['id'] . "\n";

​
Example Response

The response returns the complete updated cardholder data: 
{
  "success": true,
  "status": 200,
  "message": "Cardholder updated successfully",
  "data": {
    "id": "CH1a2b3c4d5e6f",
    "externalId": "F45786646",
    "firstName": "John",
    "lastName": "Smith",
    "email": "johnsmith@example.com",
    "phone": "+19287654321",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "address": {
      "line1": "456 Oak Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "zipCode": "90001"
    },
    "document": {
      "type": "PASSPORT",
      "number": "AB1234567"
    },
    "kyc": {
      "status": "UNSUBMITTED",
      "idFrontUrl": null,
      "idBackUrl": null,
      "selfieUrl": null
    },
    "status": "ACTIVE",
    "metadata": {
      "department": "Sales",
      "badge_number": "B-789"
    },
    "createdAt": "2026-01-15 21:31:39",
    "updatedAt": "2026-01-16T00:37:34+00:00"
  },
  "meta": {
    "requestId": "req_7d30cd59796bbcf0e903b5fd",
    "timestamp": "2026-01-16T00:37:34+00:00"
  }
}

​
Suspend/Reactivate Cardholder

You can change the cardholder’s status to temporarily suspend or reactivate them: 
// Suspend a cardholder
{ "status": "SUSPENDED" }

// Reactivate a cardholder
{ "status": "ACTIVE" }

// Mark as inactive
{ "status": "INACTIVE" }
Suspending a cardholder does not automatically suspend their cards. You should manage card statuses separately if needed.
The email field cannot be updated after cardholder creation. If you need to change the email, you must delete the cardholder and create a new one.
The documentType and documentNumber fields are locked once the cardholder’s KYC status is ACCEPTED or SUBMITTED. You cannot modify document information after KYC verification.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

​
id
string
required

Unique cardholder identifier

Body

application/json
​
firstName
string

Cardholder's first name

Required string length: 1 - 100
​
lastName
string

Cardholder's last name

Required string length: 1 - 100
​
phone
string

Phone number with country code

Required string length: 6 - 20
​
dateOfBirth
string<date>

Date of birth (YYYY-MM-DD)

​
gender
enum<string>

Gender

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
​
country
string

ISO 3166-1 alpha-2 country code

Required string length: 2
​
zipCode
string

Postal/ZIP code

Maximum string length: 20
​
documentType
enum<string>

Type of identification document

Available options:
PASSPORT,
NATIONAL_ID,
DRIVER_LICENSE
​
documentNumber
string

Document identification number

Maximum string length: 50
​
externalId
string

Your system's identifier

Maximum string length: 100
​
status
enum<string>

Cardholder status

Available options:
ACTIVE,
INACTIVE,
SUSPENDED

Response

Cardholder updated successfully

Response for create and update cardholder operations

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
​
data
object
​
meta
object