Zal Ultra API Documentation

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

Overview

Complete API documentation for the Zal Ultra ISP Management System.

Important

Most API endpoints require authentication. You must first obtain an access token by calling the User Login or Subscriber Login endpoint before accessing protected resources.

---

Authentication

To access protected endpoints, include the Bearer token in your request header:

Authorization: Bearer your-auth-token

Getting Your Token

1. Call the login endpoint with your credentials
2. Extract the token from the response
3. Include it in all subsequent requests as Authorization: Bearer {token}
4. Renew it with the refresh-token endpoint before expires_at

Token rules

Tokens live 30 days (server-configurable) and are rotated on refresh. They are revoked immediately when the user is disabled, the user's password is changed, or a logout endpoint is called — an expired or revoked token cannot be refreshed, so always handle 401 by logging in again. Full rules: Auth → Token Expiry.

Code Examples

Every endpoint page includes ready-to-run examples in cURL, PHP, JavaScript, Python, Go and Rust. Pick a language tab once — the whole site remembers your choice.

📁 Quickstart: login → refresh → create a subscriber →

Common Headers

Header	Value	Required
Accept	application/json	Yes
Content-Type	application/json	Yes (POST/PUT)

Common Query Parameters

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP identifier
branch_id	integer	Yes	Branch identifier
user_id	integer	Yes	User identifier

---

API Modules

1. Public Endpoints

No authentication required

Method	Endpoint	Description
GET	/api/health	Health check

📁 View Public API →

---

2. Authentication

User Authentication

Method	Endpoint	Description
POST	/api/v1/users/login	Admin/Staff login (30-day token)
GET	/api/v1/users/profile	Get current user
POST	/api/v1/users/refresh-token	Refresh token
POST	/api/v1/users/logout	Logout (current token)
POST	/api/v1/users/logout-all	Logout all devices

📁 View User Auth →

Subscriber Authentication

Method	Endpoint	Description
POST	/api/v1/subscriber/login	Subscriber login (30-day token)
GET	/api/v1/subscriber/profile	Get profile
POST	/api/v1/subscriber/refresh-token	Refresh token
POST	/api/v1/subscriber/logout	Subscriber logout
POST	/api/v1/subscriber/logout-all	Logout all devices

📁 View Subscriber Auth →

---

3. Subscriber Portal

Requires subscriber authentication token

Method	Endpoint	Description
GET	/api/v1/subscriber/profile	Get profile
GET	/api/v1/subscriber/package	Get package info
GET	/api/v1/subscriber/invoices	Get invoices
GET	/api/v1/subscriber/payments	Get payments
GET	/api/v1/subscriber/usage	Get usage stats
POST	/api/v1/subscriber/change-password	Change password

📁 View Subscriber Portal →

---

4. User (Admin/Staff) API

Requires admin/staff authentication token

Subscriber Management

Method	Endpoint	Description
GET	/api/v1/subscribers	Fetch all subscribers
GET	/api/v1/subscribers/{id}	Fetch subscriber
POST	/api/v1/subscribers	Create subscriber
PUT	/api/v1/subscribers/{id}	Update subscriber
DELETE	/api/v1/subscribers/{id}	Delete subscriber
POST	/api/v1/subscribers/{id}/activate	Activate subscriber
POST	/api/v1/subscribers/{id}/suspend	Suspend subscriber
POST	/api/v1/subscribers/import	Import subscribers
GET	/api/v1/subscribers/export	Export subscribers

📁 View Subscribers API →

---

User Management

Method	Endpoint	Description
GET	/api/v1/users	Fetch all users
GET	/api/v1/users/{id}	Fetch user
POST	/api/v1/users	Create user
PUT	/api/v1/users/{id}	Update user
DELETE	/api/v1/users/{id}	Delete user
GET	/api/v1/users/resellers	Fetch resellers
GET	/api/v1/users/staff	Fetch staff

📁 View Users API →

---

Package Management

Method	Endpoint	Description
GET	/api/v1/packages	Fetch all packages
GET	/api/v1/packages/{id}	Fetch package
POST	/api/v1/packages	Create package
PUT	/api/v1/packages/{id}	Update package
DELETE	/api/v1/packages/{id}	Delete package
POST	/api/v1/packages/assign	Assign package
GET	/api/v1/packages/pricing	Get pricing

📁 View Packages API →

---

Invoice Management

Method	Endpoint	Description
GET	/api/v1/invoices	Fetch all invoices
GET	/api/v1/invoices/{id}	Fetch invoice
POST	/api/v1/invoices	Create invoice
PUT	/api/v1/invoices/{id}	Update invoice
DELETE	/api/v1/invoices/{id}	Delete invoice
POST	/api/v1/invoices/generate	Generate invoice
POST	/api/v1/invoices/{id}/pay	Pay invoice
POST	/api/v1/invoices/{id}/reverse	Reverse invoice

📁 View Invoices API →

---

Payment Management

Method	Endpoint	Description
GET	/api/v1/payments	Fetch all payments
GET	/api/v1/payments/{id}	Fetch payment
POST	/api/v1/payments	Create payment
PUT	/api/v1/payments/{id}	Update payment
DELETE	/api/v1/payments/{id}	Delete payment
GET	/api/v1/payments/methods	Get payment methods

📁 View Payments API →

---

Ledger Management

Method	Endpoint	Description
GET	/api/v1/ledgers	Fetch all ledgers
GET	/api/v1/ledgers/{id}	Fetch ledger
GET	/api/v1/ledgers/history	Ledger history

📁 View Ledgers API →

---

Dashboard

Method	Endpoint	Description
GET	/api/v1/dashboard/stats	Dashboard statistics
GET	/api/v1/dashboard/charts	Dashboard charts

📁 View Dashboard API →

---

Settings

Method	Endpoint	Description
GET	/api/v1/settings/general	Get general settings
PUT	/api/v1/settings/general	Update general settings
GET	/api/v1/settings/software	Get software settings
PUT	/api/v1/settings/software	Update software settings
GET	/api/v1/settings/sms	Get SMS settings
PUT	/api/v1/settings/sms	Update SMS settings

📁 View Settings API →

---

OLT/ONU Management

Method	Endpoint	Description
GET	/api/v1/olts	Fetch all OLTs
GET	/api/v1/olts/{id}	Fetch OLT
POST	/api/v1/olts	Create OLT
PUT	/api/v1/olts/{id}	Update OLT
DELETE	/api/v1/olts/{id}	Delete OLT
POST	/api/v1/olts/{id}/sync	Sync OLT
GET	/api/v1/onus	Fetch all ONUs
POST	/api/v1/onus/{id}/command	Send ONU command

📁 View OLT/ONU API →

---

Policies

Method	Endpoint	Description
GET	/api/v1/policies	Fetch all policies
GET	/api/v1/policies/{id}	Fetch policy
POST	/api/v1/policies	Create policy
PUT	/api/v1/policies/{id}	Update policy
DELETE	/api/v1/policies/{id}	Delete policy

📁 View Policies API →

---

Extra Fees

Method	Endpoint	Description
GET	/api/v1/extra-fees	Fetch all extra fees
GET	/api/v1/extra-fees/{id}	Fetch extra fee
POST	/api/v1/extra-fees	Create extra fee
PUT	/api/v1/extra-fees/{id}	Update extra fee
DELETE	/api/v1/extra-fees/{id}	Delete extra fee
DELETE	/api/v1/extra-fees/group/{id}	Delete extra fee group

📁 View Extra Fees API →

---

Bandwidth Allocations

Method	Endpoint	Description
GET	/api/v1/bandwidth	Fetch all bandwidth allocations
GET	/api/v1/bandwidth/{id}	Fetch bandwidth
POST	/api/v1/bandwidth	Create bandwidth
PUT	/api/v1/bandwidth/{id}	Update bandwidth
DELETE	/api/v1/bandwidth/{id}	Delete bandwidth
DELETE	/api/v1/bandwidth/group/{id}	Delete bandwidth group

📁 View Bandwidth API →

---

NAS (Network Access Server)

Method	Endpoint	Description
GET	/api/v1/nas	Fetch all NAS
GET	/api/v1/nas/{id}	Fetch NAS
POST	/api/v1/nas	Create NAS
PUT	/api/v1/nas/{id}	Update NAS
DELETE	/api/v1/nas/{id}	Delete NAS
POST	/api/v1/nas/{id}/test	Test NAS connection

📁 View NAS API →

---

IP Pools

Method	Endpoint	Description
GET	/api/v1/ip-pools	Fetch all IP pools
GET	/api/v1/ip-pools/{id}	Fetch IP pool
POST	/api/v1/ip-pools	Create IP pool
PUT	/api/v1/ip-pools/{id}	Update IP pool
DELETE	/api/v1/ip-pools/{id}	Delete IP pool
POST	/api/v1/ip-pools/{id}/generate	Generate IPs

📁 View IP Pools API →

---

Areas

Method	Endpoint	Description
GET	/api/v1/areas	Fetch all areas
GET	/api/v1/areas/{id}	Fetch area
POST	/api/v1/areas	Create area
PUT	/api/v1/areas/{id}	Update area
DELETE	/api/v1/areas/{id}	Delete area
GET	/api/v1/areas/hierarchy	Fetch area hierarchy

📁 View Areas API →

---

Tickets

Method	Endpoint	Description
GET	/api/v1/tickets	Fetch all tickets
GET	/api/v1/tickets/{id}	Fetch ticket
POST	/api/v1/tickets	Create ticket
PUT	/api/v1/tickets/{id}	Update ticket
DELETE	/api/v1/tickets/{id}	Delete ticket
POST	/api/v1/tickets/{id}/reply	Reply to ticket
PUT	/api/v1/tickets/{id}/status	Change ticket status

📁 View Tickets API →

---

Roles

Method	Endpoint	Description
GET	/api/v1/roles	Fetch all roles
GET	/api/v1/roles/{id}	Fetch role
POST	/api/v1/roles	Create role
PUT	/api/v1/roles/{id}	Update role
DELETE	/api/v1/roles/{id}	Delete role
POST	/api/v1/roles/{id}/copy	Copy role

📁 View Roles API →

---

Permissions

Method	Endpoint	Description
GET	/api/v1/permissions	Fetch all permissions
GET	/api/v1/permissions/grouped	Fetch grouped permissions

📁 View Permissions API →

---

Notes

Method	Endpoint	Description
GET	/api/v1/notes	Fetch all notes
GET	/api/v1/notes/{id}	Fetch note
POST	/api/v1/notes	Create note
PUT	/api/v1/notes/{id}	Update note
DELETE	/api/v1/notes/{id}	Delete note

📁 View Notes API →

---

Notices

Method	Endpoint	Description
GET	/api/v1/notices	Fetch all notices
GET	/api/v1/notices/{id}	Fetch notice
POST	/api/v1/notices	Create notice
PUT	/api/v1/notices/{id}	Update notice
DELETE	/api/v1/notices/{id}	Delete notice

📁 View Notices API →

---

Email Templates

Method	Endpoint	Description
GET	/api/v1/email-templates	Fetch all email templates
GET	/api/v1/email-templates/{id}	Fetch email template
POST	/api/v1/email-templates	Create email template
PUT	/api/v1/email-templates/{id}	Update email template
DELETE	/api/v1/email-templates/{id}	Delete email template

📁 View Email Templates API →

---

SMS Templates

Method	Endpoint	Description
GET	/api/v1/sms-templates	Fetch all SMS templates
GET	/api/v1/sms-templates/{id}	Fetch SMS template
POST	/api/v1/sms-templates	Create SMS template
PUT	/api/v1/sms-templates/{id}	Update SMS template
DELETE	/api/v1/sms-templates/{id}	Delete SMS template

📁 View SMS Templates API →

---

Activity Logs

Method	Endpoint	Description
GET	/api/v1/activity-logs	Fetch all activity logs
GET	/api/v1/activity-logs/{id}	Fetch activity log
GET	/api/v1/activity-logs/by-subject	Fetch logs by subject
GET	/api/v1/activity-logs/by-user/{id}	Fetch logs by user

📁 View Activity Logs API →

---

ISPs

Method	Endpoint	Description
GET	/api/v1/isps	Fetch all ISPs
GET	/api/v1/isps/{id}	Fetch ISP
POST	/api/v1/isps	Create ISP
PUT	/api/v1/isps/{id}	Update ISP
DELETE	/api/v1/isps/{id}	Delete ISP

📁 View ISPs API →

---

Branches

Method	Endpoint	Description
GET	/api/v1/branches	Fetch all branches
GET	/api/v1/branches/{id}	Fetch branch
POST	/api/v1/branches	Create branch
PUT	/api/v1/branches/{id}	Update branch
DELETE	/api/v1/branches/{id}	Delete branch

📁 View Branches API →

---

Inventory

Method	Endpoint	Description
GET	/api/v1/inventory	Fetch all inventory
GET	/api/v1/inventory/{id}	Fetch inventory item
POST	/api/v1/inventory	Create inventory item
PUT	/api/v1/inventory/{id}	Update inventory item
DELETE	/api/v1/inventory/{id}	Delete inventory item
POST	/api/v1/inventory/{id}/assign	Assign inventory
POST	/api/v1/inventory/{id}/unassign	Unassign inventory

📁 View Inventory API →

---

Expenses

Method	Endpoint	Description
GET	/api/v1/expenses	Fetch all expenses
GET	/api/v1/expenses/categories	Fetch expense categories
GET	/api/v1/expenses/{id}	Fetch expense
POST	/api/v1/expenses	Create expense
PUT	/api/v1/expenses/{id}	Update expense
DELETE	/api/v1/expenses/{id}	Delete expense

📁 View Expenses API →

---

MAC Binding

Method	Endpoint	Description
GET	/api/v1/mac-binding	Fetch all MAC bindings
GET	/api/v1/mac-binding/{id}	Fetch subscriber MAC
POST	/api/v1/mac-binding/bind	Bind MAC address
POST	/api/v1/mac-binding/unbind	Unbind MAC address

📁 View MAC Binding API →

---

Reports

Method	Endpoint	Description
GET	/api/v1/reports/subscriber-summary	Subscriber summary
GET	/api/v1/reports/revenue-summary	Revenue summary
GET	/api/v1/reports/package-distribution	Package distribution
GET	/api/v1/reports/salesperson-performance	Salesperson performance
GET	/api/v1/reports/expiring-subscribers	Expiring subscribers
GET	/api/v1/reports/daily-collection	Daily collection

📁 View Reports API →

---

RADIUS

Method	Endpoint	Description
GET	/api/v1/radius/online-sessions	Online sessions
GET	/api/v1/radius/session-history	Session history
GET	/api/v1/radius/radcheck/{username}	Get subscriber radcheck
GET	/api/v1/radius/radreply/{username}	Get subscriber radreply
GET	/api/v1/radius/radusergroup/{username}	Get subscriber radusergroup
GET	/api/v1/radius/usage-stats/{username}	Get usage stats
POST	/api/v1/radius/disconnect	Disconnect session

📁 View RADIUS API →

---

SMS

Method	Endpoint	Description
POST	/api/v1/sms/send	Send SMS
POST	/api/v1/sms/send-to-subscriber	Send SMS to subscriber
POST	/api/v1/sms/send-bulk	Send bulk SMS

📁 View SMS API →

---

Balance

Method	Endpoint	Description
GET	/api/v1/balance/subscriber/{id}	Get subscriber balance
GET	/api/v1/balance/user/{id}	Get user balance
POST	/api/v1/balance/subscriber/add	Add subscriber balance
GET	/api/v1/balance/subscriber/{id}/ledger	Get subscriber ledger

📁 View Balance API →

---

5. Payment Gateways

Bkash Integration

Method	Endpoint	Description
POST	/api/queryBill	Query bill
POST	/api/payBill	Pay bill
POST	/api/searchTransaction	Search transaction

📁 View Payment Gateways →

---

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
500	Server Error

---

Error Response Format

{
    "success": false,
    "message": "Error description",
    "errors": {
        "field_name": ["Validation error message"]
    }
}

---

Environment Variables

Variable	Description
zalultra_url	Base URL of the API server
zalultra_token	Admin/Staff authentication token
subscriber_token	Subscriber authentication token
zalultra_email	Admin login email
zalultra_password	Admin login password
zalultra_sub_username	Subscriber login username
zalultra_sub_password	Subscriber login password

---

Quick Reference

Method Colors

• GET - Retrieve data
• POST - Create/Action
• PUT - Update
• DELETE - Delete

Required Fields

Fields marked with Required or in red are mandatory.