curl --request POST \
--url https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}/kyc/import \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"source": "EXTERNAL_PROVIDER",
"reference": "kyc-2026-000123",
"provider": "Our onboarding team",
"decision": "APPROVED",
"verifiedAt": "2026-11-02T10:15:00Z",
"document": {
"documentType": "PASSPORT",
"documentNumber": "AB123456",
"issuingCountry": "KE",
"issuingDate": "2022-03-01",
"expiryDate": "2032-02-28",
"frontUrl": "https://files.example.com/kyc/front.jpg",
"selfieUrl": "https://files.example.com/kyc/selfie.jpg"
}
}
'{
"success": true,
"status": 123,
"message": "<string>",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"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",
"country": "US",
"state": "Delaware",
"postalCode": "19701"
},
"kycDocument": {
"documentType": "PASSPORT",
"documentNumber": "••••3456",
"issuingCountry": "US",
"issuingDate": "2019-03-04",
"expiryDate": "2029-03-03"
},
"externalId": "usr_123456",
"metadata": {
"plan": "premium"
},
"status": "ACTIVE",
"kycStatus": "APPROVED",
"kycVerifiedAt": "2026-05-10T14:23:00Z",
"kycRejectionReason": null,
"totalCards": 2,
"suspendedAt": null,
"terminatedAt": null,
"createdAt": "2026-05-01T09:00:00Z",
"updatedAt": "2026-05-10T14:23:00Z",
"programEligibility": [
{
"programCode": "FYT-USD-02",
"programName": "USD Global Tier 2",
"eligible": false,
"requiresVerification": true,
"reason": "<string>",
"bins": [
{
"binCode": "SGVISAV01",
"binName": "Virtual Card - Singapore BIN",
"bin": "49372410",
"issuingCountry": "SG",
"scheme": "VISA",
"formFactor": "VIRTUAL",
"requiresVerification": true,
"eligible": true,
"reason": "<string>",
"verificationStatus": "NOT_SUBMITTED",
"canSubmit": true,
"verificationMessage": "<string>"
}
]
}
],
"importedVerification": {
"source": "<string>",
"provider": "<string>",
"reference": "<string>",
"sourceDecision": "<string>",
"sourceVerifiedAt": "<string>",
"sessionId": "<string>",
"importedAt": "2023-11-07T05:31:56Z",
"importedBy": "<string>"
}
}
}Cardholders
Import an Existing Verification
Bring in a verification you already performed elsewhere instead of collecting documents again. POST /cardholders//kyc/import. Requires cardholders:write scope.
POST
/
cardholders
/
{id}
/
kyc
/
import
curl --request POST \
--url https://sandbox-api.fyatu.com/api/v3.20/cardholders/{id}/kyc/import \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"source": "EXTERNAL_PROVIDER",
"reference": "kyc-2026-000123",
"provider": "Our onboarding team",
"decision": "APPROVED",
"verifiedAt": "2026-11-02T10:15:00Z",
"document": {
"documentType": "PASSPORT",
"documentNumber": "AB123456",
"issuingCountry": "KE",
"issuingDate": "2022-03-01",
"expiryDate": "2032-02-28",
"frontUrl": "https://files.example.com/kyc/front.jpg",
"selfieUrl": "https://files.example.com/kyc/selfie.jpg"
}
}
'{
"success": true,
"status": 123,
"message": "<string>",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"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",
"country": "US",
"state": "Delaware",
"postalCode": "19701"
},
"kycDocument": {
"documentType": "PASSPORT",
"documentNumber": "••••3456",
"issuingCountry": "US",
"issuingDate": "2019-03-04",
"expiryDate": "2029-03-03"
},
"externalId": "usr_123456",
"metadata": {
"plan": "premium"
},
"status": "ACTIVE",
"kycStatus": "APPROVED",
"kycVerifiedAt": "2026-05-10T14:23:00Z",
"kycRejectionReason": null,
"totalCards": 2,
"suspendedAt": null,
"terminatedAt": null,
"createdAt": "2026-05-01T09:00:00Z",
"updatedAt": "2026-05-10T14:23:00Z",
"programEligibility": [
{
"programCode": "FYT-USD-02",
"programName": "USD Global Tier 2",
"eligible": false,
"requiresVerification": true,
"reason": "<string>",
"bins": [
{
"binCode": "SGVISAV01",
"binName": "Virtual Card - Singapore BIN",
"bin": "49372410",
"issuingCountry": "SG",
"scheme": "VISA",
"formFactor": "VIRTUAL",
"requiresVerification": true,
"eligible": true,
"reason": "<string>",
"verificationStatus": "NOT_SUBMITTED",
"canSubmit": true,
"verificationMessage": "<string>"
}
]
}
],
"importedVerification": {
"source": "<string>",
"provider": "<string>",
"reference": "<string>",
"sourceDecision": "<string>",
"sourceVerifiedAt": "<string>",
"sessionId": "<string>",
"importedAt": "2023-11-07T05:31:56Z",
"importedBy": "<string>"
}
}
}Overview
If you already verified this person — in a partner verification application, with another provider, or through your own process — send us that verification instead of putting them through a second one. Two kinds of evidence are accepted:source | What you send |
|---|---|
SHARED_SESSION | shareToken: a session shared from a partner verification application |
EXTERNAL_PROVIDER | document: the verification record itself, with its images |
What you send is evidence, not a verdict. Your
decision is recorded as provenance and shown
on the cardholder; the cardholder’s status is decided by our own screening of the document and
images, exactly as for any other submission. An import saves a collection round-trip; it does not
approve a cardholder on your say-so.Request Body
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | Yes | Your own identifier for this verification. Makes a retry safe |
source | string | No | SHARED_SESSION or EXTERNAL_PROVIDER. Inferred when omitted: a request with shareToken is a shared session, one with document is a provider record |
shareToken | string | For SHARED_SESSION | The token that redeems the shared session. Redeemable once |
document | object | For EXTERNAL_PROVIDER | The verification record: documentType, documentNumber, issuingCountry, issuingDate, expiryDate, frontUrl, backUrl, selfieUrl |
provider | string | No | Who performed the verification, in your words. Recorded as given |
decision | string | No | What the source concluded, e.g. APPROVED. Recorded as provenance only |
verifiedAt | string | No | When the source verified the person, RFC 3339 |
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/kyc/import \
-H "Authorization: Bearer $FYATU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": "EXTERNAL_PROVIDER",
"reference": "kyc-2026-000123",
"provider": "Our onboarding team",
"decision": "APPROVED",
"verifiedAt": "2026-11-02T10:15:00Z",
"document": {
"documentType": "PASSPORT",
"documentNumber": "AB123456",
"issuingCountry": "KE",
"issuingDate": "2022-03-01",
"expiryDate": "2032-02-28",
"frontUrl": "https://files.example.com/kyc/front.jpg",
"selfieUrl": "https://files.example.com/kyc/selfie.jpg"
}
}'
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/kyc/import \
-H "Authorization: Bearer $FYATU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "source": "SHARED_SESSION", "reference": "share-7731", "shareToken": "st_4b1e9c0d" }'
Success Response (201)
The cardholder, with the status our screening reached — orPENDING while it is still running, in
which case the decision arrives on your KYC webhook — plus what we recorded about the import:
{
"success": true,
"status": 201,
"message": "Verification imported",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"kycStatus": "PENDING",
"importedVerification": {
"source": "EXTERNAL_PROVIDER",
"provider": "Our onboarding team",
"reference": "kyc-2026-000123",
"sourceDecision": "APPROVED",
"sourceVerifiedAt": "2026-11-02T10:15:00Z",
"importedAt": "2026-11-09T08:00:00Z"
}
}
}
data object also carries every other cardholder field, as in
Get Cardholder.
Error Codes
| Code | HTTP | Cause |
|---|---|---|
INVALID_REQUEST | 400 | reference missing; shareToken missing for a shared session; document missing for a provider record; an invalid or expired share token; a record without a document and its images |
CARDHOLDER_NOT_FOUND | 404 | No such cardholder under your business |
KYC_ALREADY_APPROVED | 409 | The cardholder is already approved |
KYC_IMPORT_ALREADY_REDEEMED | 409 | This share token was already redeemed; its verification arrived the first time |
CARDHOLDER_TERMINATED | 422 | The cardholder is terminated |
SERVICE_UNAVAILABLE | 503 | Shared sessions cannot be accepted right now; send the verification record instead, or retry later |
In the sandbox
The sandbox redeems shared sessions without a partner: theshareToken chooses the outcome.
shareToken | Result |
|---|---|
sandbox_invalid | 400 INVALID_REQUEST: invalid or expired token |
sandbox_redeemed | 409: already imported |
| anything else | imported with the sandbox’s specimen passport, then decided as any sandbox cardholder is (see the quickstart) |
Authorizations
Body
application/json

