Skip to main content
POST
/
subscribers
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",
    "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://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",
    "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://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"
  }'

​
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

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Body

application/json

Subscriber registration details

​
first_name
string
required
Example:

"John"

​
last_name
string
required
Example:

"Doe"

​
phone_number
string
required
Example:

"0771234567"

​
pin
string
required
Example:

"1234"

​
address
string
Example:

"123 Main St"

​
category
string
Example:

"retail"

​
certificate_url
string
Example:

"https://example.com/cert.pdf"

​
district
string
Example:

"Western Urban"

​
email
string
Example:

"john@example.com"

​
id_back_url
string
Example:

"https://example.com/id_back.jpg"

​
id_front_url
string
Example:

"https://example.com/id_front.jpg"

​
kyc_level
integer
Example:

1

​
max_child_cards
integer
Example:

4

​
national_id
string
Example:

"NID123456"

​
organisation_name
string
Example:

"ABC Company Ltd"

​
organisation_type
string
Example:

"Limited Company"

​
other_names
string
Example:

"Michael"

​
referral_code
string
Example:

"REF123"

​
registration_id_no
string
Example:

"RC123456"

​
relationship_manager_id
integer
Example:

1

​
whatsapp_number
string
Example:

"0771234567"

Response

Subscriber created successfully

The response is of type object.