KYC Rail

Customer verification and identity management endpoints.

Overview

The KYC rail provides comprehensive customer verification:

• Identity verification
• Document verification
• Sanctions screening
• PEP (Politically Exposed Persons) checks

Endpoints

Create Verification

POST /v1/kyc/verifications

const verification = await iof.kyc.createVerification({
  customerId: "cust_123",
  type: "identity",
  documents: [
    { type: "passport", fileId: "file_abc" },
    { type: "proof_of_address", fileId: "file_def" },
  ],
});

Response:

{
  "id": "kyc_verification_xyz",
  "status": "pending",
  "customerId": "cust_123",
  "type": "identity",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Verification

GET /v1/kyc/verifications/:id

const verification = await iof.kyc.getVerification("kyc_verification_xyz");

List Verifications

GET /v1/kyc/verifications

const verifications = await iof.kyc.listVerifications({
  customerId: "cust_123",
  status: "verified",
  limit: 20,
});

Upload Document

POST /v1/kyc/documents

const document = await iof.kyc.uploadDocument({
  customerId: "cust_123",
  type: "passport",
  file: fileBuffer,
  metadata: {
    country: "MY",
    expiryDate: "2028-01-01",
  },
});

Screen Customer

POST /v1/kyc/screen

const screening = await iof.kyc.screen({
  customerId: "cust_123",
  checks: ["sanctions", "pep", "adverse_media"],
});

Response:

{
  "id": "screen_abc",
  "customerId": "cust_123",
  "results": {
    "sanctions": { "matched": false },
    "pep": { "matched": false },
    "adverse_media": { "matched": false, "hits": 0 }
  },
  "riskScore": 15,
  "recommendation": "approve"
}

Verification Status

Status	Description
pending	Awaiting processing
in_review	Manual review required
verified	Successfully verified
rejected	Verification failed
expired	Verification expired

Document Types

Type	Description
passport	Passport document
national_id	National ID card
drivers_license	Driver's license
proof_of_address	Utility bill, bank statement
company_registration	Business registration

Webhooks

Event	Description
kyc.submitted	Verification submitted
kyc.verified	Verification approved
kyc.rejected	Verification rejected
kyc.expired	Verification expired

Next Steps

• Compliance Rail - Compliance checks
• AML Rail - Anti-money laundering