API Reference

Complete reference for the Keshless REST API.

Base URLs

Environment	URL
Production	https://api.keshless.app
Development	https://dev-api.keshless.app

---

API Categories

Core APIs

Category	Base Path	Description
Authentication	/auth	User, vendor, and admin authentication
Users	/users	User profiles, settings, notifications
Vendors	/vendors	Vendor CRUD, operations, sub-users, tills
Wallet	/wallet	Balance, transfers, payments

Transaction APIs

Category	Base Path	Description
Cards	/cards	Card linking and management
Transactions	/transactions	Transaction history and details
Withdrawal Requests	/withdrawal-requests	Vendor-initiated withdrawals

KYC & Verification APIs (Documented)

• KYC Users - User identity verification
• Verification Workflow - Document and selfie verification
• Vendor KYC - Business verification for vendors

AML & Compliance APIs (Documented)

• Risk Scoring - Transaction risk assessment
• SAR Management - Suspicious Activity Reports
• PEP Management - Politically Exposed Persons screening
• Rules Engine - Configurable compliance rules

Accounting APIs (Documented)

• Ledger Service - Journal entries and reversals
• Transaction Templates - Pre-built double-entry patterns
• Posting Service - Pending to posted workflow
• Balance Verification - Reconciliation logic
• Trial Balance - Financial reporting
• Statements - User and vendor account statements
• Chart of Accounts - Account structure management

Admin APIs

Category	Base Path	Description
Admin Employees	/admin/employees	RBAC user management
System Config	/admin/config	Fees, limits, PIN configuration
Emergency Controls	/admin/emergency	Kill switches and lockdowns
Audit Logs	/admin/audit-logs	Activity and change logs

Integration APIs

Category	Base Path	Description
Integrations	/integrations	API key management
Partner API	/integration	External payment endpoints

---

Authentication

Methods

Type	Usage	Header
JWT Bearer	User, vendor, admin sessions	Authorization: Bearer <token>
API Key	Partner integrations	X-API-Key: <key>
Public	Health, fees, public info	None required

Token Endpoints

POST /auth/user/login          # User login
POST /auth/user/register       # User registration
POST /auth/vendor/login        # Vendor login
POST /auth/admin/login         # Admin login
POST /auth/refresh             # Refresh access token

---

Common Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Operation completed"
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid phone number format"
  }
}

Paginated Response

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

---

Common Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
sortBy	string	Field to sort by
sortOrder	string	asc or desc
startDate	ISO date	Filter from date
endDate	ISO date	Filter to date

---

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - validation failed
401	Unauthorized - invalid/missing token
403	Forbidden - insufficient permissions
404	Not Found
409	Conflict - duplicate resource
429	Rate Limited
500	Internal Server Error

---

Rate Limiting

• Standard endpoints: 100 requests/minute
• Authentication endpoints: 10 requests/minute
• Bulk operations: 10 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706140800

---

Getting Started

1. Register via /auth/user/register or /auth/vendor/register
2. Verify phone with OTP sent via SMS/WhatsApp
3. Login to receive JWT access token
4. Include token in all authenticated requests

---

Detailed Documentation

Explore the documented API services:

Compliance & Verification:

• KYC Users
• Verification Workflow
• Vendor KYC
• Risk Scoring
• SAR Management
• PEP Management
• Rules Engine

Accounting System:

• Ledger Service
• Posting Service
• Balance Verification
• Trial Balance
• Statements
• Chart of Accounts