KYC Users API
API endpoints for managing KYC users, including listing, searching, and user history retrieval.
Base URL: /admin/users
Endpoints Summary
| Method | Endpoint | Description |
|---|---|---|
| GET | /admin/users | List users with filtering |
| GET | /admin/users/:id | Get user details |
| GET | /admin/users/search | Search users |
| PUT | /admin/users/:id | Update user |
| DELETE | /admin/users/:id | Archive user |
| POST | /admin/users/:id/unarchive | Restore archived user |
| GET | /admin/users/stats | Get aggregate statistics |
| GET | /admin/users/:id/verifications | Get user verifications |
| GET | /admin/users/:id/transactions | Get user transactions |
| GET | /admin/users/:id/documents | Get user KYC documents |
| GET | /admin/users/:id/history | Get complete user history |
| POST | /admin/users/search-by-phone | Find user by phone |
| POST | /admin/users/:id/add-balance | Add balance (admin) |
| DELETE | /admin/users/:id/purge | Permanently delete user |
List Users
GET /admin/users
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
limit | number | 20 | Items per page |
verificationStatus | string | - | Filter by verification status |
riskRating | string | - | Filter by risk rating |
search | string | - | Search term |
hasCard | boolean | - | Filter users with/without NFC card |
isArchived | boolean | - | Include archived users |
Returns: Paginated list of user objects with id, phoneNumber, email, firstName, lastName, verificationStatus, riskRating, currentRiskScore, balance, isVerified, createdAt
Get User by ID
GET /admin/users/:id
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | User UUID |
Returns: Full user object including:
| Field | Type | Description |
|---|---|---|
id | string | User UUID |
phoneNumber | string | Phone with country code |
email | string | Email address |
firstName, lastName | string | Name fields |
names, surname | string | Legacy name fields |
idNumber | string | Government ID number |
dateOfBirth | string | YYYY-MM-DD format |
sex | string | MALE or FEMALE |
verificationStatus | string | PENDING, VERIFIED, REJECTED |
riskRating | string | LOW, MEDIUM, HIGH |
currentRiskScore | number | 0-100 risk score |
balance | number | Wallet balance in Emalageni |
nfcCardNumber | string | Linked NFC card |
rewardsPoints | number | Current rewards balance |
referralCode | string | User's referral code |
isVerified | boolean | Verification complete |
isArchived | boolean | Soft-deleted status |
Search Users
GET /admin/users/search?q={searchTerm}
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
q | string | Search term (min 3 characters) |
page | number | Page number |
limit | number | Items per page |
Searches: Name, phone, email, ID number
Returns: Paginated list of matching users with basic info
Update User
PUT /admin/users/:id
Updatable Fields:
| Field | Type | Description |
|---|---|---|
firstName | string | First name |
lastName | string | Last name |
email | string | Email address |
Returns: Updated user object
Archive / Unarchive User
- Archive:
DELETE /admin/users/:id- Soft deletes the user - Unarchive:
POST /admin/users/:id/unarchive- Restores archived user
Get User Statistics
GET /admin/users/stats
Returns:
| Field | Description |
|---|---|
totalUsers | Total registered users |
verifiedUsers | Users with completed KYC |
pendingVerification | Awaiting verification |
rejectedVerification | Failed verification |
newUsersToday | Today's registrations |
newUsersThisWeek | This week's registrations |
newUsersThisMonth | This month's registrations |
Get User Verifications
GET /admin/users/:id/verifications
Returns: List of verification records with id, status, type, createdAt, completedAt
Get User Transactions
GET /admin/users/:id/transactions
Returns: List of transactions with id, type, amount, status, createdAt
Get User Documents
GET /admin/users/:id/documents
Returns: List of KYC documents with:
| Document Type | Description |
|---|---|
ID_FRONT | Front of ID document |
ID_BACK | Back of ID document |
SELFIE | User selfie for face verification |
Each includes type, url, uploadedAt
Get User Full History
GET /admin/users/:id/history
Returns: Complete user history including:
- User profile data
- All verifications
- All transactions
- All documents
- Timeline of events
- Aggregate statistics (
totalTransactions,totalVolume,avgTransaction,daysActive)
Search User by Phone
POST /admin/users/search-by-phone
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
phoneNumber | string | Yes | Phone with country code (e.g., +26878123456) |
Returns: User with id, phoneNumber, firstName, lastName, fullName, verificationStatus, isVerified, nfcCardNumber
Use Case: Card linking in vendor app
Add Balance
POST /admin/users/:id/add-balance
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount in Emalageni |
reason | string | Yes | Reason for credit |
Returns: previousBalance, addedAmount, newBalance
Note: Admin-only action for promotional credits or corrections
Purge User
DELETE /admin/users/:id/purge
Warning: Permanently deletes user and all associated data. Cannot be undone.
Error Responses
| Status | Error | Description |
|---|---|---|
| 404 | User not found | Invalid user ID |
| 400 | Search term is required | Missing search query |
| 400 | Validation error | Invalid request body |