Users & KYC

Users are the cardholders of your program. A user must have a verified email, a linked wallet, and approved KYC before a card can be created.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

POST /users

Create a user.

// Request
{
  "email": "[email protected]",
  "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
  "chain": "polygon"
}

// Response
{
  "id": "usr_9f4c",
  "email": "[email protected]",
  "emailVerified": false,
  "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
  "kycStatus": "not_started",
  "createdAt": "2026-07-19T14:00:00Z"
}

GET /users/{id}

Retrieve a user's profile, verification state, and linked resources (vaults, cards).

GET /users

List your program's users. Supports limit, cursor, and kycStatus filters.

KYC

Identity verification runs through a hosted flow provided by the platform's verification partner. You never handle identity documents.

POST /users/{id}/kyc/session

Create a verification session and receive the URL to redirect or embed:

// Response
{
  "url": "https://verify.web3card.dev/s/usr_9f4c?vt=abc123",
  "expiresIn": 1800
}

KYC statuses

Status	Meaning
not_started	No session created yet
pending	Documents submitted, under review
approved	Verification passed; cards can be created
rejected	Verification failed; details in the webhook payload

Status changes are pushed as kyc.approved / kyc.rejected webhooks and are also readable on the user profile.

Phone verification

Some jurisdictions require a verified phone number:

• POST /users/{id}/phone/otp: send SMS code
• POST /users/{id}/phone/verify: confirm code