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