Skip to main content
GET
/
subscribers
curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers" \
  -H "Authorization: Bearer olive_live_xxx"

{
  "subscribers": [
    {
      "id": "sub_abc123",
      "phone_number": "+23279123456",
      "first_name": "John",
      "last_name": "Doe",
      "kyc_level": 2,
      "status": "ACTIVE",
      "balance": "125,000.00 SLE",
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "sub_def456",
      "phone_number": "+23279654321",
      "first_name": "Jane",
      "last_name": "Smith",
      "kyc_level": 1,
      "status": "ACTIVE",
      "balance": "50,000.00 SLE",
      "created_at": "2025-01-14T09:15:00Z"
    }
  ],
  "total_count": 1250,
  "limit": 50,
  "offset": 0
}

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)

​
Query Parameters

​
status
string
Filter by status: ACTIVE, BLOCKED, PENDING
​
kyc_level
integer
Filter by KYC level: 1, 2, or 3
​
search
string
Search by name or phone number
​
limit
integer
default:"50"
Results per page (max 100)
​
offset
integer
default:"0"
Pagination offset

​
Response

​
subscribers
array
Array of subscriber objects
​
total_count
integer
Total number of matching subscribers
​
limit
integer
Current page size
​
offset
integer
Current offset

​
Examples

curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers" \
  -H "Authorization: Bearer olive_live_xxx"

{
  "subscribers": [
    {
      "id": "sub_abc123",
      "phone_number": "+23279123456",
      "first_name": "John",
      "last_name": "Doe",
      "kyc_level": 2,
      "status": "ACTIVE",
      "balance": "125,000.00 SLE",
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "sub_def456",
      "phone_number": "+23279654321",
      "first_name": "Jane",
      "last_name": "Smith",
      "kyc_level": 1,
      "status": "ACTIVE",
      "balance": "50,000.00 SLE",
      "created_at": "2025-01-14T09:15:00Z"
    }
  ],
  "total_count": 1250,
  "limit": 50,
  "offset": 0
}

​
Pagination

Use limit and offset for pagination. Check total_count to determine total pages.
# Page 1
GET /api/v1/subscribers?limit=20&offset=0

# Page 2
GET /api/v1/subscribers?limit=20&offset=20

# Page 3
GET /api/v1/subscribers?limit=20&offset=40

​
Permissions

This endpoint requires admin-level permissions. Agents can only see their own subscribers.

​
Errors

StatusCodeDescription
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENInsufficient permissions
500INTERNAL_ERRORServer error

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
page
integer

Page number (default 1)

​
page_size
integer

Page size (default 50)

​
status
string

Filter by status (active, blocked, pending)

​
kyc_level
integer

Filter by KYC level (1, 2, 3)

​
district
string

Filter by district

Response

List of subscribers

The response is of type object.