Skip to main content
POST
/
api
/
v1
/
subscribers
curl -X POST "https://olive-gateway-a6ba.onrender.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",
    "email": "john@example.com",
    "date_of_birth": "1990-05-15"
  }'

{
  "success": true,
  "subscriber_id": "sub_abc123",
  "message": "Subscriber registered successfully",
  "subscriber": {
    "id": "sub_abc123",
    "phone_number": "+23279123456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "kyc_level": 1,
    "status": "ACTIVE",
    "balance": "0.00 SLE",
    "created_at": "2025-01-15T10:30:00Z"
  }
}
For public registration without authentication, use the Public Registration endpoint instead.

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)
​
Content-Type
string
required
application/json

​
Body Parameters

​
phone_number
string
required
Phone number in local format (0771234567) or E.164 (+23279123456)
​
first_name
string
required
Subscriber’s first name
​
last_name
string
required
Subscriber’s last name
​
pin
string
required
4-digit PIN for transactions (e.g., 1234)
​
email
string
Email address
​
date_of_birth
string
Date of birth (YYYY-MM-DD format)
​
address
string
Physical address
​
id_number
string
National ID number
​
id_type
string
ID document type: NATIONAL_ID, PASSPORT, DRIVERS_LICENSE
​
id_document_url
string
URL to uploaded ID document image
​
selfie_url
string
URL to uploaded selfie for KYC verification
​
max_child_cards
integer
default:"4"
Maximum child cards allowed

​
Response

​
success
boolean
Whether registration succeeded
​
subscriber_id
string
Unique subscriber UUID (e.g., sub_abc123)
​
message
string
Human-readable result message
​
subscriber
object
Full subscriber object with all fields

​
Examples

curl -X POST "https://olive-gateway-a6ba.onrender.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",
    "email": "john@example.com",
    "date_of_birth": "1990-05-15"
  }'

{
  "success": true,
  "subscriber_id": "sub_abc123",
  "message": "Subscriber registered successfully",
  "subscriber": {
    "id": "sub_abc123",
    "phone_number": "+23279123456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "kyc_level": 1,
    "status": "ACTIVE",
    "balance": "0.00 SLE",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

​
KYC Levels

Upon registration, subscribers start at KYC Level 1 with basic limits:
LevelMax BalanceDaily LimitRequired
1500,000 SLE100,000 SLEPhone + PIN
22,000,000 SLE500,000 SLE+ ID Document
310,000,000 SLE2,000,000 SLE+ Address Proof

​
Public Registration

For third-party integrations that don’t have API keys, use the public endpoint.
POST /api/v1/public/subscribers
Same request body, no Authorization header required. Rate limited per IP. 
curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/public/subscribers" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0771234567",
    "first_name": "John",
    "last_name": "Doe",
    "pin": "1234"
  }'

​
Errors

StatusCodeDescription
400INVALID_REQUESTMissing required fields or invalid format
400INVALID_PINPIN must be exactly 4 digits
401UNAUTHORIZEDInvalid or missing API key
409DUPLICATE_PHONEPhone number already registered
500INTERNAL_ERRORServer error