List Subscribers - OLIVE Payment Platform

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

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 -X GET "https://demo.api.vultlocal.com/api/v1/subscribers?search=John" \
  -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
}

GET

subscribers

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

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 -X GET "https://demo.api.vultlocal.com/api/v1/subscribers?search=John" \
  -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

string

required

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

string

Filter by status: ACTIVE, BLOCKED, PENDING

integer

Filter by KYC level: 1, 2, or 3

string

Search by name or phone number

integer

default:"50"

Results per page (max 100)

integer

default:"0"

Pagination offset

Response

array

Array of subscriber objects

integer

Total number of matching subscribers

integer

Current page size

integer

Current offset

Examples

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

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 -X GET "https://demo.api.vultlocal.com/api/v1/subscribers?search=John" \
  -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

Status	Code	Description
401	`UNAUTHORIZED`	Invalid or missing API key
403	`FORBIDDEN`	Insufficient permissions
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'

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.

Get Subscriber

Update Subscriber

​Request

​Query Parameters

​Response

​Examples

​Pagination

​Permissions

​Errors

Authorizations

Query Parameters

Response

Request

Query Parameters

Response

Examples

Pagination

Permissions

Errors