Customer Management Module¶

Overview¶

The Customer Management module handles customer profiles, KYC/verification, contact information, and customer data management. It serves as the central repository for customer information accessed by all other modules.

API Prefix: /api/v1/customer

Route Verification Status¶

Source Router: app/api/v1/endpoints/customer.py
Live Route Count: 24
Verification State: Verified (2026-06-28)
Canonical Tracking: docs/API_ROUTE_DOCUMENTATION_TODO.md
Verification Method: Route decorators extracted from @r.<method>(...) in app/api/v1/endpoints/customer.py.

Key Features¶

1. Customer Registration & Profiles¶

New customer onboarding
Profile creation with basic information
Multi-channel registration (Web, Mobile, USSD, Agent)
Customer data validation
Profile completeness tracking

2. Contact Information Management¶

Multiple phone numbers per customer
Multiple email addresses per customer
Multiple physical addresses per customer
Primary contact designation
Contact verification and validation

3. KYC (Know Your Customer)¶

Tier-based KYC levels
Document collection and storage
Automated KYC verification
KYC status tracking
KYC expiration and renewal

4. Customer Segmentation¶

Demographic segmentation
Risk-based segmentation
Channel preference tracking
Product usage patterns
Engagement scoring

5. Customer Data Management¶

Centralized customer data repository
Data quality monitoring
Duplicate detection and merging
Customer staging (data import)
Historical data tracking

6. Customer Search & Discovery¶

Search by phone, email, name, ID
Advanced filtering capabilities
Customer lookup and verification
Account linking

7. Customer Account Management¶

View associated accounts and wallets
View transactions and loan history
View campaign participation
Customer activity dashboard

API Endpoints (Verified Against Live Router)¶

For the complete customer endpoint inventory (all 24 routes with method, effective path, and source line), use: - docs/API_ROUTE_LIVE_REFERENCE.md -> section customer.py (24 routes)

Permission Dependency Notes (Verified)¶

Confirmed explicit permission checks in customer.py include: - Customer lifecycle: create_customer, edit_customer, dispose_customer, decline_customer, get_customer, stage_customer, fetch_customer, download_customer. - Account operations: fetch_account, get_account, create_account. - Dictionary lookups: fetch_customer_type, fetch_account_type, fetch_address_type, fetch_phone_type, fetch_email_type, fetch_customer_category, fetch_customer_employer_category, fetch_customer_employment, fetch_customer_industry, fetch_customer_education, fetch_customer_income, fetch_customer_mno.

Standard Error Response Matrix¶

{
  "status_code": 400,
  "error_code": "CUSTOMER_ERROR",
  "message": "Human-readable summary",
  "details": {}
}

Common mappings: - 400 invalid customer state transition or business rule failure. - 401 unauthenticated request. - 403 permission denied. - 404 customer/account/resource not found. - 409 duplicate or conflicting customer/account state. - 422 schema validation failure. - 429 throttled request. - 500 internal processing error.

Database Models¶

Core Customer Models¶

Customer: Main customer record (ID, name, status, registration date)
Profile: Extended customer information (DOB, gender, occupation, income)
Phone: Phone numbers with verification status
Email: Email addresses with verification status
Address: Physical addresses with verification status
Account: Bank accounts linked to customer

KYC & Verification¶

KYCStatus: Current KYC level and verification status
KYCDocument: Uploaded KYC documents (ID, Address Proof, Income Proof)
KYCVerification: KYC verification audit trail
IdentityProvider: Links to external identity verification providers

Data Management¶

CustomerStaging: Temporary storage for imported customers
CustomerMergeRecord: Track merged customer records
CustomerChangeLog: Historical changes to customer data

Customer Segmentation¶

CustomerSegment: Segment assignment (premium, standard, basic)
RiskProfile: Risk assessment for each customer
EngagementScore: Customer engagement metrics

Customer Onboarding Flow¶

Standard Onboarding (Web/Mobile)¶

1. Registration
   ├─ Email/Phone collection
   ├─ Password setup
   ├─ Terms & conditions acceptance
   └─ Create customer record

2. Basic Profile
   ├─ Name and personal info
   ├─ Date of birth
   ├─ Occupation/Business type
   └─ Profile saved

3. Initial Verification
   ├─ Email verification (link)
   ├─ Phone verification (OTP)
   ├─ Contact information confirmed
   └─ Account activated for basic features

4. Document Collection (KYC)
   ├─ Upload ID document
   ├─ Upload address proof
   ├─ Optional: Income proof
   └─ Documents queued for verification

5. KYC Verification
   ├─ Manual review or automated verification
   ├─ Document validation
   ├─ Customer tier assignment
   └─ Full feature access granted

6. Account Linking (Optional)
   ├─ Link bank accounts for transfers
   ├─ Add wallet funding sources
   └─ Complete onboarding

Agent/USSD Onboarding¶

1. Agent Enters Customer Info
   ├─ Phone number
   ├─ Name and ID number
   ├─ Address
   └─ Customer created

2. Document Collection
   ├─ Agent captures/uploads ID photo
   ├─ Address proof photo
   └─ Documents queued for verification

3. Quick Activation
   ├─ Customer can access USSD/Mobile immediately
   ├─ Limits restricted until full KYC
   └─ Upgrade to full access after verification

Customer Tiers/Segments¶

Tier 1: Basic¶

Min KYC: Phone verified
Max balance: 10,000
Max transaction: 5,000
Access: USSD, Mobile limited
Features: P2P transfer, basic bill payment

Tier 2: Standard¶

Min KYC: Full ID verified
Max balance: 50,000
Max transaction: 25,000
Access: Full mobile, USSD, Web
Features: All P2P, merchant, loans (basic)

Tier 3: Premium¶

Min KYC: Full KYC + income proof
Max balance: 500,000
Max transaction: 250,000
Access: All channels, priority support
Features: Loans (unlimited), business accounts

Tier 4: Business¶

Min KYC: Business registration + beneficial owner KYC
Unlimited balance/transactions
Access: Dedicated business dashboard
Features: Batch payments, API access, reporting

Controllers & Business Logic¶

Key Controllers¶

controller/customer.py: Customer operations
create_customer(): Register new customer
update_profile(): Update customer information
search_customer(): Query customers
get_customer_details(): Retrieve full profile
controller/contact.py: Contact management
add_phone(): Add phone number
add_email(): Add email address
add_address(): Add physical address
verify_contact(): Verify via OTP/link
controller/kyc.py: KYC verification
initiate_kyc(): Start KYC process
submit_documents(): Upload documents
verify_documents(): Verify and approve
assign_tier(): Assign customer tier
controller/customer_staging.py: Bulk import
create_staging_record(): Create staged customer
validate_staged_data(): Validate import data
import_staged_customers(): Bulk import

Configuration¶

Onboarding Configuration¶

{
  "channels": {
    "web": {
      "kyc_required": "immediate",
      "email_verification": true,
      "phone_verification": true
    },
    "mobile": {
      "kyc_required": "within_7_days",
      "email_verification": false,
      "phone_verification": true
    },
    "ussd": {
      "kyc_required": "within_30_days",
      "email_verification": false,
      "phone_verification": true
    },
    "agent": {
      "kyc_required": "within_1_day",
      "email_verification": false,
      "phone_verification": true
    }
  }
}

KYC Configuration¶

{
  "tiers": [
    {
      "level": 1,
      "name": "Basic",
      "documents_required": ["phone"],
      "max_balance": 10000
    },
    {
      "level": 2,
      "name": "Standard", 
      "documents_required": ["id", "address"],
      "max_balance": 50000
    },
    {
      "level": 3,
      "name": "Premium",
      "documents_required": ["id", "address", "income"],
      "max_balance": 500000
    }
  ],
  "verification_methods": ["manual", "automated"],
  "id_types": ["passport", "national_id", "drivers_license"]
}

Integration Points¶

External Services¶

ID Verification Service: Automated ID validation
Address Verification: Address validation APIs
Email Verification: Email confirmation links
SMS/OTP: Phone number verification
Credit Bureau: KYC and risk assessment

Internal Modules¶

Authentication: Verify customer identity
Wallet: Link to wallets
Loan: Customer loan applications
Transaction: Customer transactions
Notification: Send verification messages
Document: Store KYC documents
Policy: Apply customer policies

Data Privacy & Compliance¶

Data Minimization: Collect only necessary data
Data Storage: Encrypt sensitive data at rest
Data Retention: Define retention periods per data type
Data Anonymization: Anonymize archived data
Consent Tracking: Track customer consent for data usage
Right to Deletion: Honor deletion requests (except legal holds)
Audit Trail: Log all data access and changes
Export: Allow customers to export their data

Error Handling¶

Common Errors¶

CUSTOMER_NOT_FOUND: Customer ID doesn't exist
DUPLICATE_CUSTOMER: Customer with same data exists
INVALID_PHONE: Invalid phone number format
INVALID_EMAIL: Invalid email address
PHONE_ALREADY_REGISTERED: Phone associated with another customer
KYC_REQUIRED: Customer must complete KYC
KYC_VERIFICATION_PENDING: KYC under review
CUSTOMER_INACTIVE: Customer account is inactive
DATA_VALIDATION_FAILED: Customer data fails validation

Testing¶

Test Categories¶

Customer registration flows
Contact management (add, verify, update)
KYC workflows
Bulk customer import
Customer search and lookup
Data validation

Test Files¶

tests/test_customer.py: Customer operations
tests/test_entity.py: Entity/customer entity tests
conftest.py: Customer test fixtures

Performance Considerations¶

Search Indexing: Index on phone, email, ID for fast lookup
Contact Caching: Cache primary contact info
KYC Caching: Cache verification status
Bulk Operations: Batch import for large datasets
Pagination: Paginate customer lists