Register Subscriber - OLIVE Payment Platform

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"
  }
}

{
  "error": "Phone number already registered",
  "code": "DUPLICATE_PHONE"
}

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"
  }
}

{
  "error": "Phone number already registered",
  "code": "DUPLICATE_PHONE"
}

For public registration without authentication, use the Public Registration endpoint instead.

Request

string

required

Bearer olive_live_xxx or Bearer eyJ... (JWT)

string

required

application/json

Body Parameters

string

required

Phone number in local format (0771234567) or E.164 (+23279123456)

string

required

Subscriber’s first name

string

required

Subscriber’s last name

string

required

4-digit PIN for transactions (e.g., 1234)

string

Email address

string

Date of birth (YYYY-MM-DD format)

string

Physical address

string

National ID number

string

ID document type: NATIONAL_ID, PASSPORT, DRIVERS_LICENSE

string

URL to uploaded ID document image

string

URL to uploaded selfie for KYC verification

integer

default:"4"

Maximum child cards allowed

Response

boolean

Whether registration succeeded

string

Unique subscriber UUID (e.g., sub_abc123)

string

Human-readable result message

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"
  }
}

{
  "error": "Phone number already registered",
  "code": "DUPLICATE_PHONE"
}

KYC Levels

Upon registration, subscribers start at KYC Level 1 with basic limits:

Level	Max Balance	Daily Limit	Required
1	500,000 SLE	100,000 SLE	Phone + PIN
2	2,000,000 SLE	500,000 SLE	+ ID Document
3	10,000,000 SLE	2,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

Status	Code	Description
400	`INVALID_REQUEST`	Missing required fields or invalid format
400	`INVALID_PIN`	PIN must be exactly 4 digits
401	`UNAUTHORIZED`	Invalid or missing API key
409	`DUPLICATE_PHONE`	Phone number already registered
500	`INTERNAL_ERROR`	Server 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"

string

required

Example:

"1234"

address

string

Example:

"123 Main St"

Response

Subscriber created successfully

The response is of type object.

Subscribers

Lookup Subscriber

​Request

​Body Parameters

​Response

​Examples

​KYC Levels

​Public Registration

​Errors

Authorizations

Body

Response

Request

Body Parameters

Response

Examples

KYC Levels

Public Registration

Errors