Subscriber Registration

This guide covers the complete subscriber registration flow, including KYC requirements and error handling.

Registration Flow

Quick Registration

Public Endpoint (No Auth)

curl -X POST https://demo.api.vultlocal.com/api/v1/public/subscribers \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0771234567",
    "first_name": "John",
    "last_name": "Doe",
    "pin": "1234"
  }'

Authenticated Endpoint

curl -X POST https://demo.api.vultlocal.com/api/v1/subscribers \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0771234567",
    "first_name": "John",
    "last_name": "Doe",
    "pin": "1234"
  }'

Required Fields

Field	Type	Validation
phone_number	string	Sierra Leone format, 8 digits after +232
first_name	string	1-100 characters
last_name	string	1-100 characters
pin	string	4 digits

KYC Levels

Basic (Default)

• Phone verification
• Name and PIN
• Limits: Daily 100,000 SLE, Monthly 500,000 SLE

Enhanced

• ID document upload via Agent
• OCR validation
• Limits: Daily 500,000 SLE, Monthly 2,000,000 SLE

Full

• Front + back ID verification
• Cross-validation passed
• Limits: Daily 2,000,000 SLE, Monthly 10,000,000 SLE

KYC Upgrade via WhatsApp

Users can upgrade KYC through the WhatsApp agent:

1. User: "I want to upgrade my account"
2. Agent: "Please send a clear photo of the FRONT of your Sierra Leone National ID"
3. User: [Sends front image]
4. Agent: "Front received. Now send the BACK of your ID"
5. User: [Sends back image]
6. Agent: "Your KYC upgrade is complete!"

Error Handling

Error	Cause	Solution
PHONE_ALREADY_REGISTERED	Phone exists	User should login instead
INVALID_PHONE_FORMAT	Wrong format	Use Sierra Leone format
WEAK_PIN	Sequential/repeated digits	Choose stronger PIN

Phone Number Format

Valid Sierra Leone formats:

+23279123456   (E.164)
079123456      (local)
23279123456    (without +)

All are normalized to +23279123456.

Best Practices

Customer Communication

Send welcome SMS after successful registration with basic instructions.

PIN Security

Never store or log PINs in plaintext. Hash before storage.

KYC Guidance

Prompt users to complete Enhanced KYC for higher limits.

Next Steps

KYC Upgrade

Document validation details

API Reference

Registration endpoint details