Skip to main content
POST
/
cardholders
/
{id}
/
kyc
Submit KYC Documents
curl --request POST \
  --url https://api.fyatu.com/api/v3/cardholders/{id}/kyc \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "PASSPORT",
  "documentNumber": "AB123456",
  "idFrontUrl": "https://storage.example.com/documents/id_front.jpg",
  "idBackUrl": "https://storage.example.com/documents/id_back.jpg",
  "selfieUrl": "https://storage.example.com/documents/selfie.jpg"
}
'
{
  "success": true,
  "status": 200,
  "message": "KYC documents submitted successfully",
  "data": {
    "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "kycStatus": "SUBMITTED",
    "message": "KYC documents submitted successfully. Verification is pending."
  }
}
Deprecated — This endpoint will be removed on July 1, 2026.Use Initiate KYC Verification (POST /cardholders/{id}/kyc/session) instead, which provides automated identity verification with liveness checks.This endpoint uploads documents to storage but does not trigger automated identity verification.

​
Overview

Submit KYC (Know Your Customer) documents manually for a cardholder. Documents are stored but not automatically verified. For automated verification with ID document scanning and liveness checks, use the Initiate KYC Verification endpoint instead.

​
Endpoint

POST /api/v3/cardholders/{cardholderId}/kyc
Scope required: cardholders:write

​
Path Parameters

ParameterTypeRequiredDescription
cardholderIdstringYesUnique cardholder identifier

​
Request Fields

FieldTypeRequiredDescription
documentTypestringYesPASSPORT, NATIONAL_ID, or DRIVER_LICENSE
documentNumberstringYesDocument identification number (3-50 chars)
idFrontUrlstringYesURL to the front image of the ID document
idBackUrlstringNoURL to the back image
selfieUrlstringNoURL to a selfie photo

​
Image Requirements

  • Format: JPEG, PNG, GIF, or WebP only
  • Maximum size: 5MB per image
  • Accessibility: URLs must be publicly accessible

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "KYC documents submitted successfully",
  "data": {
    "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "kycStatus": "SUBMITTED",
    "message": "KYC documents submitted successfully."
  },
  "meta": {
    "requestId": "req_kyc123abc",
    "timestamp": "2026-01-08T17:00:00+00:00"
  }
}

​
Migration Guide

Replace calls to this endpoint with the new two-step flow: 
// Old (deprecated)
await fetch(`/api/v3/cardholders/${id}/kyc`, {
  method: 'POST',
  body: JSON.stringify({
    documentType: 'PASSPORT',
    documentNumber: 'AB123456',
    idFrontUrl: 'https://...',
  })
});

// New (recommended)
const { data } = await fetch(`/api/v3/cardholders/${id}/kyc/session`, {
  method: 'POST'
}).then(r => r.json());

// Redirect cardholder to complete verification
window.location.href = data.verificationUrl;

// Listen for webhook: cardholder.kyc_approved or cardholder.kyc_rejected

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

​
id
string
required

Unique cardholder identifier

Body

application/json
​
documentType
enum<string>
required

Type of identification document

Available options:
PASSPORT,
NATIONAL_ID,
DRIVER_LICENSE
​
documentNumber
string
required

Document identification number

Required string length: 3 - 50
​
idFrontUrl
string<uri>
required

URL to the front image of the ID document

Maximum string length: 500
​
idBackUrl
string<uri>

URL to the back image of the ID document (optional for passports)

Maximum string length: 500
​
selfieUrl
string<uri>

URL to a selfie photo holding the ID document

Maximum string length: 500

Response

KYC documents submitted successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
Example:

"KYC documents submitted successfully"

​
data
object