Skip to content

User - Subscribers

Base URL: https://your-domain.com

Admin endpoints for managing subscribers. All endpoints require admin/staff authentication.


Fetch All Subscribers

Retrieve a paginated list of subscribers with optional filters and relationship modules.

PropertyValue
EndpointFetch All Subscribers
MethodGET
URL/api/v1/subscribers
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Query Parameters:

Required Parameters

ParameterTypeRequiredDescription
isp_idintegerYesISP ID
branch_idintegerYesBranch ID

Pagination Parameters

ParameterTypeRequiredDescription
offsetintegerNoPagination offset (default: 0)
limitintegerNoResults per page (default: 100)

Filter Parameters

ParameterTypeRequiredDescription
subscriber_idintegerNoGet single subscriber by ID
salesperson_idintegerNoFilter by salesperson ID
package_idintegerNoFilter by package ID
nas_idintegerNoFilter by NAS ID
searchstringNoSearch by username, email, phone, fullname, or identity
subscriber_typeintegerNoFilter by status (0=Inactive, 1=Pending, 2=Active, 3=Expired, 4=Disabled, 7=Online)
expiring_inintegerNoFilter expiring subscribers (1=1 day, 2=3 days, 3=1 week, 4=2 weeks)
grace_period_statusintegerNoFilter by grace period status (0=No, 1=Yes)
departmentintegerNoFilter by department ID

Location Filter Parameters

ParameterTypeRequiredDescription
countryintegerNoFilter by country ID
provinceintegerNoFilter by province ID
cityintegerNoFilter by city ID
areaintegerNoFilter by area ID
subareaintegerNoFilter by subarea ID

Module Loading Parameters

Use all_module_status=1 to load all relationships at once, or enable individual modules for optimized performance:

ParameterTypeRequiredDescription
all_module_statusintegerNoLoad ALL relationship modules at once (1=Yes)
package_moduleintegerNoLoad package data (1=Yes)
salesperson_moduleintegerNoLoad salesperson data (1=Yes)
nas_moduleintegerNoLoad NAS data (1=Yes)
radacct_moduleintegerNoLoad RADIUS accounting data (1=Yes)
radchecks_moduleintegerNoLoad RADIUS check attributes (1=Yes)
radreply_moduleintegerNoLoad RADIUS reply attributes (1=Yes)
radusergroup_moduleintegerNoLoad RADIUS user group data (1=Yes)
ip_pool_moduleintegerNoLoad IP pool and address data (1=Yes)
balance_moduleintegerNoLoad current balance data (1=Yes)
area_moduleintegerNoLoad area hierarchy data (1=Yes)
invoice_moduleintegerNoLoad invoices data (1=Yes)
ledger_moduleintegerNoLoad ledger entries (1=Yes)
payment_moduleintegerNoLoad payments data (1=Yes)

Request Body: None

Success Response (200 OK):

json
{
    "success": true,
    "data": {
        "subscribers": [
            {
                "id": 1,
                "username": "subscriber001",
                "fullname": "John Doe",
                "email": "[email protected]",
                "phone": "01712345678",
                "package_id": 1,
                "package_name": "10MB Package",
                "status": "active",
                "expiration_date": "2025-12-31 23:59:59",
                "balance": 500.00,
                "created_at": "2024-01-15 10:30:00"
            }
        ],
        "total": 150,
        "offset": 0,
        "limit": 100
    }
}

Error Response (401 Unauthorized):

json
{
    "success": false,
    "message": "Unauthenticated"
}

Error Response (403 Forbidden):

json
{
    "success": false,
    "message": "You do not have permission to view subscribers"
}

cURL Example:

bash
# Basic fetch with required parameters
curl -X GET "https://your-domain.com/api/v1/subscribers?isp_id=1&branch_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

# With pagination and filters
curl -X GET "https://your-domain.com/api/v1/subscribers?isp_id=1&branch_id=1&offset=0&limit=50&subscriber_type=2&package_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

# With module loading
curl -X GET "https://your-domain.com/api/v1/subscribers?isp_id=1&branch_id=1&package_module=1&balance_module=1&area_module=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

Get Subscriber Details

Retrieve detailed profile information for a single subscriber.

PropertyValue
EndpointGet Subscriber Details
MethodGET
URL/api/v1/subscribers/details
AuthenticationBearer Token

Query Parameters:

ParameterTypeRequiredDescription
idintegerYesSubscriber ID
isp_idintegerYesISP ID
branch_idintegerYesBranch ID

Request Body: None

Success Response (200 OK):

json
{
    "success": true,
    "data": {
        "id": 1,
        "username": "subscriber001",
        "fullname": "John Doe",
        "email": "[email protected]",
        "phone": "01712345678",
        "address": "123 Main Street",
        "identity": "1234567890",
        "package_id": 1,
        "package_name": "10MB Package",
        "nas_id": 1,
        "static_ip": "192.168.1.100",
        "mac_address": "AA:BB:CC:DD:EE:FF",
        "status": "active",
        "expiration_date": "2025-12-31 23:59:59",
        "balance": 500.00,
        "salesperson_id": 1,
        "salesperson_name": "Sales User",
        "created_at": "2024-01-15 10:30:00"
    }
}

Error Response (404 Not Found):

json
{
    "success": false,
    "message": "Subscriber not found"
}

cURL Example:

bash
curl -X GET "https://your-domain.com/api/v1/subscribers/details?id=1&isp_id=1&branch_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

Create Subscriber

Create a new subscriber account.

PropertyValue
EndpointCreate Subscriber
MethodPOST
URL/api/v1/subscribers/create
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Content-Typeapplication/jsonYes
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Request Body:

json
{
    "isp_id": 1,
    "branch_id": 1,
    "username": "subscriber001",
    "fullname": "John Doe",
    "password": "pass123",
    "package_id": 1,
    "salesperson_id": 1,
    "connection_password": "conn123",
    "static_ip": "192.168.1.100",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "expiration_date": "2025-12-31 23:59:59",
    "previous_balance": 0,
    "email": "[email protected]",
    "phone": "01712345678",
    "identity": "1234567890",
    "address": "123 Main Street",
    "nas_id": 1,
    "connection_type": 0,
    "profile_status": 0,
    "country": 1,
    "province": 1,
    "city": 1,
    "area": 1,
    "subarea": 1,
    "department": 1,
    "latitude": "23.8103",
    "longitude": "90.4125",
    "auto_renew_status": 1,
    "discount": 0,
    "discount_type": 0,
    "sms_status": 1,
    "email_status": 1,
    "mac_lock_status": 0,
    "total_data_quota": 0,
    "total_session_quota": 0,
    "join_date": "2025-01-01",
    "onu_note": "ONU installed",
    "box_number": "BOX-001",
    "box_address": "Building A",
    "switch_board": "SW-01",
    "switch_port": "Port 1",
    "electric_socket": "Socket A",
    "cable_type": "Fiber",
    "uplink_port": "UP-01",
    "fiber_code": "FC-001",
    "fiber_color": "Blue"
}

Required Parameters

ParameterTypeRequiredDescription
isp_idintegerYesISP ID
branch_idintegerYesBranch ID
usernamestringYesUnique username for login
fullnamestringYesSubscriber's full name
passwordstringYesLogin password
package_idintegerYesPackage ID to assign

Connection Parameters

ParameterTypeRequiredDescription
salesperson_idintegerNoAssigned salesperson ID
connection_passwordstringNoPPPoE/RADIUS connection password
static_ipstringNoStatic IP address
mac_addressstringNoMAC address for binding
nas_idintegerNoNAS ID for RADIUS
connection_typeintegerNoConnection type (0=PPPoE, 1=Hotspot, etc.)
mac_lock_statusintegerNoMAC lock status (0=Disabled, 1=Enabled)

Profile Parameters

ParameterTypeRequiredDescription
expiration_datedatetimeNoAccount expiration date (format: YYYY-MM-DD HH:mm:ss)
previous_balancedecimalNoOpening balance amount
profile_statusintegerNoInitial status (0=Inactive, 1=Pending, 2=Active)
auto_renew_statusintegerNoAuto-renewal (0=Disabled, 1=Enabled)
discountdecimalNoDiscount amount
discount_typeintegerNoDiscount type (0=Fixed, 1=Percentage)
join_datedateNoJoin date (format: YYYY-MM-DD)

Contact Parameters

ParameterTypeRequiredDescription
emailstringNoEmail address
phonestringNoPhone number
identitystringNoNational ID / Passport number
addressstringNoFull address
sms_statusintegerNoSMS notifications (0=Disabled, 1=Enabled)
email_statusintegerNoEmail notifications (0=Disabled, 1=Enabled)

Location Parameters

ParameterTypeRequiredDescription
countryintegerNoCountry ID
provinceintegerNoProvince ID
cityintegerNoCity ID
areaintegerNoArea ID
subareaintegerNoSubarea ID
departmentintegerNoDepartment ID
latitudestringNoGPS latitude coordinate
longitudestringNoGPS longitude coordinate

Quota Parameters

ParameterTypeRequiredDescription
total_data_quotaintegerNoTotal data quota in MB (0=Unlimited)
total_session_quotaintegerNoTotal session quota in minutes (0=Unlimited)

Infrastructure Parameters (ONU/Fiber)

ParameterTypeRequiredDescription
onu_notestringNoONU installation notes
box_numberstringNoDistribution box number
box_addressstringNoDistribution box location
switch_boardstringNoSwitch board identifier
switch_portstringNoSwitch port number
electric_socketstringNoElectric socket identifier
cable_typestringNoCable type (Fiber, UTP, etc.)
uplink_portstringNoUplink port identifier
fiber_codestringNoFiber cable code
fiber_colorstringNoFiber cable color

Success Response (201 Created):

json
{
    "success": true,
    "message": "Subscriber created successfully",
    "data": {
        "id": 1,
        "username": "subscriber001"
    }
}

Error Response (422 Validation Error):

json
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "username": ["The username has already been taken."]
    }
}

cURL Example:

bash
curl -X POST "https://your-domain.com/api/v1/subscribers/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "isp_id": 1,
    "branch_id": 1,
    "username": "subscriber001",
    "fullname": "John Doe",
    "password": "pass123",
    "package_id": 1,
    "email": "[email protected]",
    "phone": "01712345678",
    "nas_id": 1,
    "salesperson_id": 1
  }'

Update Subscriber

Update an existing subscriber's information.

PropertyValue
EndpointUpdate Subscriber
MethodPUT
URL/api/v1/subscribers/update
AuthenticationBearer Token

Request Body:

json
{
    "id": 1,
    "isp_id": 1,
    "branch_id": 1,
    "fullname": "John Doe Updated",
    "phone": "01712345679"
}
ParameterTypeRequiredDescription
idintegerYesSubscriber ID
isp_idintegerYesISP ID
branch_idintegerYesBranch ID
Other fieldsvariousNoAny subscriber field to update

Success Response (200 OK):

json
{
    "success": true,
    "message": "Subscriber updated successfully"
}

Error Response (404 Not Found):

json
{
    "success": false,
    "message": "Subscriber not found"
}

cURL Example:

bash
curl -X PUT "https://your-domain.com/api/v1/subscribers/update" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "id": 1,
    "isp_id": 1,
    "branch_id": 1,
    "fullname": "John Doe Updated",
    "phone": "01712345679"
  }'

Delete Subscriber

Permanently delete a subscriber account.

PropertyValue
EndpointDelete Subscriber
MethodDELETE
URL/api/v1/subscribers/delete
AuthenticationBearer Token

Query Parameters:

ParameterTypeRequiredDescription
idintegerYesSubscriber ID
isp_idintegerYesISP ID
branch_idintegerYesBranch ID
user_idintegerYesAdmin user ID performing deletion

Request Body: None

Success Response (200 OK):

json
{
    "success": true,
    "message": "Subscriber deleted successfully"
}

Error Response (404 Not Found):

json
{
    "success": false,
    "message": "Subscriber not found"
}

cURL Example:

bash
curl -X DELETE "https://your-domain.com/api/v1/subscribers/delete?id=1&isp_id=1&branch_id=1&user_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

Activate/Invoice Subscriber

Activate a subscriber and generate an invoice with optional custom expiry date. Supports package change during activation - pass a different package_id to activate with a new package.

PropertyValue
EndpointActivate Subscriber
MethodPOST
URL/api/v1/subscribers/activation
AuthenticationBearer Token

Request Body:

json
{
    "subscriber_id": 1,
    "package_id": 5,
    "payment_amount": 1000,
    "payment_method": 1,
    "cut_subscriber_balance": 1,
    "custom_expiry_datetime": "2026-12-31 23:59:59"
}

Required Parameters

ParameterTypeRequiredDescription
subscriber_idintegerYesSubscriber ID to activate

Optional Parameters

ParameterTypeRequiredDescription
package_idintegerNoNew package ID for package change during activation. If not provided, uses subscriber's current package. Must be assigned to the subscriber's salesperson.
payment_amountdecimalNoPayment amount to add to subscriber balance before activation
payment_methodintegerNoPayment method ID (default: 1=Cash). Common values: 1=Cash, 4=Subscriber Balance, 6=Bkash, etc.
cut_subscriber_balanceintegerNoSet to 1 to pay from subscriber balance. This overrides payment_method to 4. Requires sufficient balance.
custom_expiry_datetimedatetimeNoCustom expiry date (format: YYYY-MM-DD HH:MM:SS). Must be a future date.

Package Change

To change a subscriber's package during activation:

  1. Pass the new package_id in the request
  2. The system will validate the package exists and belongs to the same ISP/Branch
  3. The system will validate the salesperson has this package assigned
  4. All billing and accounting will be calculated based on the new package
  5. On successful activation, the subscriber's package will be updated

Success Response (200 OK):

json
{
    "status": "success",
    "message": "Subscriber Activated Successfully.",
    "subscriber_id": 1,
    "subscriber_username": "john_doe",
    "invoice_data": {
        "id": 123,
        "billing_total_amount": 1000,
        "billing_due_amount": 0,
        "invoice_status": 1
    },
    "subscriber_data": {
        "id": 1,
        "username": "john_doe",
        "package_id": 5,
        "profile_status": 2,
        "expiration_date": "2026-12-31 23:59:59"
    }
}

Error Responses:

json
// Subscriber not found
{
    "status": "error",
    "message": "Subscriber Not Found"
}

// Package not found (when package_id provided)
{
    "status": "error",
    "message": "Package Not Found"
}

// Package ISP/Branch mismatch
{
    "status": "error",
    "message": "Package Does Not Belong To Subscriber ISP/Branch"
}

// Salesperson doesn't have package assigned
{
    "status": "error",
    "message": "Invalid Salesperson or Package Data"
}

// Insufficient subscriber balance
{
    "status": "error",
    "message": "Insufficient Subscriber Balance Required (1000)"
}

// Invalid custom expiry date
{
    "status": "error",
    "message": "Custom Expiration Date/Time Invalid! Must Be A Future Date."
}

// Due invoice exists
{
    "status": "error",
    "message": "Due Invoice Already Exist (Wait 1 Hour to Generate New One Or Pay On Due Invoice)",
    "invoice_id": 122,
    "due_amount": 500,
    "subscriber_id": 1
}

cURL Examples:

bash
# Basic activation with current package
curl -X POST "https://your-domain.com/api/v1/subscribers/activation" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "subscriber_id": 1,
    "payment_amount": 1000,
    "cut_subscriber_balance": 1
  }'

# Activation with package change
curl -X POST "https://your-domain.com/api/v1/subscribers/activation" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "subscriber_id": 1,
    "package_id": 5,
    "payment_amount": 1500,
    "cut_subscriber_balance": 1
  }'

# Activation with custom expiry date
curl -X POST "https://your-domain.com/api/v1/subscribers/activation" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "subscriber_id": 1,
    "custom_expiry_datetime": "2026-12-31 23:59:59"
  }'

Mass Activation

Bulk activate multiple subscribers in a single request. This endpoint replicates the exact logic from MassActivationController for 95%+ compatibility with web view functionality.

PropertyValue
EndpointMass Activation
MethodPOST
URL/api/v1/subscribers/mass-activation
AuthenticationBearer Token

Request Body:

json
{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "selected_subscribers": "1,2,3",
    "package_id": "current_package",
    "payment_type": 1,
    "custom_expiry_datetime": "2025-12-31 23:59:59"
}
ParameterTypeRequiredDescription
isp_idintegerYesISP ID
branch_idintegerYesBranch ID
user_idintegerYesAdmin user ID
selected_subscribersstringYesComma-separated subscriber IDs
package_idmixedYesPackage ID or "current_package"
payment_typeintegerYes1=Subscriber Balance, 2=Salesperson Balance, 3=Smart
custom_expiry_datetimedatetimeNoCustom expiry date for all

Success Response (200 OK):

json
{
    "success": true,
    "message": "3 subscribers activated successfully",
    "data": {
        "activated": 3,
        "failed": 0
    }
}

cURL Example:

bash
curl -X POST "https://your-domain.com/api/v1/subscribers/mass-activation" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "selected_subscribers": "1,2,3",
    "package_id": "current_package",
    "payment_type": 1
  }'

Package Migration

Migrate a subscriber to a new package.

PropertyValue
EndpointPackage Migration
MethodPOST
URL/api/v1/subscribers/migration
AuthenticationBearer Token

Request Body:

json
{
    "subscriber_id": 1,
    "new_package_id": 2,
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1
}

Success Response (200 OK):

json
{
    "success": true,
    "message": "Package migrated successfully",
    "data": {
        "old_package": "10MB Package",
        "new_package": "20MB Package"
    }
}

cURL Example:

bash
curl -X POST "https://your-domain.com/api/v1/subscribers/migration" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "subscriber_id": 1,
    "new_package_id": 2,
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1
  }'

Attributes

Subscriber attribute management for RADIUS (radcheck/radreply).


Get Subscriber Attributes

Retrieve all RADIUS attributes for a subscriber.

PropertyValue
EndpointGet Subscriber Attributes
MethodGET
URL/api/v1/subscribers/attributes
AuthenticationBearer Token

Query Parameters:

ParameterTypeRequiredDescription
subscriber_idintegerYesSubscriber ID
isp_idintegerYesISP ID
branch_idintegerYesBranch ID

Success Response (200 OK):

json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "attribute": "Framed-IP-Address",
            "op": ":=",
            "value": "192.168.1.100"
        }
    ]
}

cURL Example:

bash
curl -X GET "https://your-domain.com/api/v1/subscribers/attributes?subscriber_id=1&isp_id=1&branch_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

Add Subscriber Attribute

Add a new RADIUS attribute to a subscriber.

PropertyValue
EndpointAdd Subscriber Attribute
MethodPOST
URL/api/v1/subscribers/attributes
AuthenticationBearer Token

Request Body:

json
{
    "subscriber_id": 1,
    "attribute": "Framed-IP-Address",
    "value": "192.168.1.100",
    "op": ":="
}

Success Response (201 Created):

json
{
    "success": true,
    "message": "Attribute added successfully",
    "data": {
        "id": 1
    }
}

cURL Example:

bash
curl -X POST "https://your-domain.com/api/v1/subscribers/attributes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "subscriber_id": 1,
    "attribute": "Framed-IP-Address",
    "value": "192.168.1.100",
    "op": ":="
  }'

Update Subscriber Attribute

Update an existing RADIUS attribute.

PropertyValue
EndpointUpdate Subscriber Attribute
MethodPUT
URL/api/v1/subscribers/attributes
AuthenticationBearer Token

Request Body:

json
{
    "id": 1,
    "value": "192.168.1.101"
}

Success Response (200 OK):

json
{
    "success": true,
    "message": "Attribute updated successfully"
}

cURL Example:

bash
curl -X PUT "https://your-domain.com/api/v1/subscribers/attributes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "id": 1,
    "value": "192.168.1.101"
  }'

Delete Subscriber Attribute

Delete a RADIUS attribute from a subscriber.

PropertyValue
EndpointDelete Subscriber Attribute
MethodDELETE
URL/api/v1/subscribers/attributes
AuthenticationBearer Token

Query Parameters:

ParameterTypeRequiredDescription
idintegerYesAttribute ID

Success Response (200 OK):

json
{
    "success": true,
    "message": "Attribute deleted successfully"
}

cURL Example:

bash
curl -X DELETE "https://your-domain.com/api/v1/subscribers/attributes?id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

www.onezeroart.com