Register Subscriber

POST/subscribersOpen in the API playground →

Info

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

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Content-Typestringheaderrequired

application/json

Body Parameters

phone_numberstringbodyrequired

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

first_namestringbodyrequired

Subscriber's first name

last_namestringbodyrequired

Subscriber's last name

pinstringbodyrequired

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

emailstringbody

Email address

date_of_birthstringbody

Date of birth (YYYY-MM-DD format)

addressstringbody

Physical address

id_numberstringbody

National ID number

id_typestringbody

ID document type: NATIONAL_ID, PASSPORT, DRIVERS_LICENSE

id_document_urlstringbody

URL to uploaded ID document image

selfie_urlstringbody

URL to uploaded selfie for KYC verification

max_child_cardsintegerbodydefault: 4

Maximum child cards allowed

---

Response

successboolean

Whether registration succeeded

subscriber_idstring

Unique subscriber UUID (e.g., sub_abc123)

messagestring

Human-readable result message

subscriberobject

Full subscriber object with all fields

---

Examples

Request

cURL

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

Response

201 Created

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

409 Conflict

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

Info

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.

Request

Public Registration

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