List Subscribers

GET/subscribersOpen in the API playground →

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

statusstringquery

Filter by status: ACTIVE, BLOCKED, PENDING

kyc_levelintegerquery

Filter by KYC level: 1, 2, or 3

searchstringquery

Search by name or phone number

limitintegerquerydefault: 50

Results per page (max 100)

offsetintegerquerydefault: 0

Pagination offset

---

Response

subscribersarray

Array of subscriber objects

total_countinteger

Total number of matching subscribers

limitinteger

Current page size

offsetinteger

Current offset

---

Examples

Request

cURL - Basic

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

cURL - With Filters

curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers?status=ACTIVE&kyc_level=2&limit=20" \
  -H "Authorization: Bearer olive_live_xxx"

cURL - Search

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

Response

200 OK

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

Info

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

Warning

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

---

Errors

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	Insufficient permissions
500	INTERNAL_ERROR	Server error