API reference

Users

92

GET /api/v1/users List subscribers prm_users_index

One page of subscribers under the caller's authority. A manager without tenant-wide visibility sees only subscribers owned by their own manager subtree, and that scope is injected server-side, so a filter can narrow within it but never widen past it.

Authentication: Staff token or session
Requires permission: prm_users_index View users
Rate limit: user_list

The per-subscriber scan token (lookup_token) is deliberately absent from list rows. It is served by GET /users/{id} and GET /users/resolve only, because a page of a thousand rows is a bulk harvest of codes that each unlock a subscriber record.

Parameters

Parameter	Description
`q` query · string	Searches username, email, first and last name, phone, contract id, national id and static IP. A purely numeric term also matches the subscriber id exactly.
`filter[enabled]` query · boolean	The admin suspend flag. Not the same thing as expired.
`filter[expired]` query · boolean	Subscription window has passed.
`filter[online]` query · boolean	An open RADIUS session exists right now.
`filter[profile_id]` query · integer	Bound plan.
`filter[parent_id]` query · integer	Owning manager. Ignored, not honoured, when it would widen a restricted caller's scope.
`filter[username_exact]` query · string	Case-insensitive exact username, for a caller that already knows the identity and wants one deterministic row instead of a page of substring hits.
`filter[expiring_within_days]` query · integer	Future expiries only.
`filter[created_from]` query · string	yyyy-MM-dd HH:mm:ss in UTC. A malformed value is a 400, not an ignored filter.

Parameter	Description
`username`required body · string	Unique within the tenant, not globally.
`password`required body · string	The RADIUS password. Stored recoverable, because CHAP and MS-CHAPv2 need it that way.
`parent_id` body · integer	Owning manager. Defaults to the caller. A subscriber is never parent-less, and a named owner must be a manager the caller may act on.
`profile_id` body · integer	Plan to bind. Must be one the acting manager may actually assign.
`expiration` body · string	yyyy-MM-dd HH:mm:ss in UTC.
`debt_limit` body · number	Credit ceiling. Omitted or null is unlimited, 0 is no credit.
`portal_password` body · string	Optional portal-only password, hashed before storage and distinct from the RADIUS password above.
`custom_fields` body · object	Tenant-defined form values, validated against the user form schema.

Parameter	Description
`id`required path · integer	Subscriber id.
`form_name` body · string	Which custom-field schema to validate custom_fields against. Defaults to the user form.

Parameter	Description
`id`required path · integer	Subscriber id.
`request_id`required body · string	Idempotency key, up to 255 characters, no colon or pipe. Reuse the same one on every retry of one intent.
`money_collected` body · boolean	Defaults to true.
`card_code` body · string	Required when method is card. The voucher must be in the caller's subtree.
`issue_invoice` body · boolean	Also record an invoice document. Skipped on a replay so a retry never double-issues.

Parameter	Description
`id`required path · integer	Subscriber id.
`bytes` body · integer	Bytes to add. At least one of bytes or seconds must be present and positive.
`seconds` body · integer	Seconds to add.

Parameter	Description
`id`required path · integer	Subscriber id.
`order`required body · array	Bucket ids in drain order. 0 is the main quota, not a missing value.

Parameter	Description
`id`required path · integer	Subscriber id.
`parent_id`required body · integer	The new owning manager.

Parameter	Description
`id`required path · integer	Subscriber id.
`amount`required body · number	Major units, a bare JSON number. 150.50, not "150.50" and not 15050.
`request_id`required body · string	Idempotency key.
`issue_invoice` body · boolean	Also record an invoice document. Skipped on a replay.

Parameter	Description
`id`required path · integer	Subscriber id.
`items`required body · array	At least one line item.

Parameter	Description
`id`required path · integer	Subscriber id.
`invoiceId`required path · integer	Invoice id.

Parameter	Description
`id`required path · integer	Subscriber id.
`clear_period` body · boolean	Also null the period quota counters. Defaults to false.
`reason` body · string	Free-text note recorded on the quota-history audit row.

Parameter	Description
`id`required path · integer	Subscriber id.
`profile_id` body · integer	Plan to price. Defaults to the subscriber's current plan.
`operation` body · enum	activate or extend. Defaults to activate.
`method` body · enum	manager_balance, user_balance, reward_points or card.
`units` body · integer	How many periods to buy.
`user_price` body · number	Retail price override. Silently ignored for a caller without the price-override permission, which then falls back to the plan or pricing-tree price.

Parameter	Description
`shared_secret`required body · string	The RADIUS shared secret. Required.
`nas_identifier` body · string	NAS-Identifier. Unique across the whole platform.
`nas_ip` body · string	NAS-IP-Address. Unique across the whole platform.
`called_station_id` body · string	Called-Station-Id. Unique across the whole platform.
`vendor` body · string	Device vendor. Validated against the known-vendor catalogue.
`coa_port` body · integer	RFC 5176 port. Omit for the schema default of 3799.
`ip_accounting_enabled` body · boolean	Defaults to true when omitted. An explicit false is honoured.

Parameter	Description
`email` body · string	Login email. Unique within the tenant. Required unless username is given.
`username` body · string	Login username. Required unless email is given.
`password`required body · string	Hashed with Argon2id before storage, unlike a subscriber's.
`parent_manager_id` body · integer	Defaults to the caller. Never null — a tenant keeps exactly one root manager, its owner. A named parent must be one the caller may act on.

Parameter	Description
`id`required path · integer	Subscriber id.
`filter[status]` query · string	Narrows to open or closed sessions.

Parameter	Description
`filter[parent_id]` query · integer	Direct children of one manager. Also accepted as a bare parent_id query parameter. Narrows within the caller's subtree, never past it.
`q` query · string	Searches name, username and email.

Parameter	Description
`id`required path · integer	Manager id.
`role_ids`required body · array	The complete new set of role ids.

Parameter	Description
`id`required path · integer	Manager id. May not be the caller themselves.
`amount`required body · number	Major units, a bare JSON number.
`request_id`required body · string	Idempotency key.
`reason` body · string	Free-text note recorded on the ledger row.
`issue_invoice` body · boolean	Also record the human-facing accounting document. Defaults to TRUE when omitted on the manager side, unlike the subscriber side.

Parameter	Description
`id`required path · integer	The debtor. May not be the caller themselves.
`amount`required body · number	Major units.
`creditor_manager_id` body · integer	Which creditor is being repaid. Absent means the debtor's parent.
`request_id`required body · string	Idempotency key.

Parameter	Description
`filter[status]` query · string	Generation status — generating, ready, failed.
`filter[card_mode]` query · string	The series mode.
`filter[owner_manager_id]` query · integer	The reseller holding the series after any transfer.
`filter[suspended]` query · boolean	Series whose unused cards have been revoked.
`filter[template_id]` query · integer	Series cut from one saved card template.
`q` query · string	Plan name, distribution note, or series id.

Parameter	Description
`type`required body · enum	refill or prepaid.
`quantity`required body · integer	How many cards to mint.
`face_value`required body · number	Value per card, major units.
`expiration`required body · string	yyyy-MM-dd HH:mm:ss or yyyy-MM-dd. Series-level card lifetime.
`plan_profile_id` body · integer	Required for prepaid, and for a refill card that auto-activates.
`code_length` body · integer	The redemption PIN length. A MINIMUM, not an exact value — a mint may exceed it when the tenant's live code pool needs more entropy.
`code_charset` body · enum	numeric, alpha, alnum or alnum_no_ambig.
`owner_manager_id` body · integer	The series owner. Defaults to the creator.
`request_id`required body · string	Idempotency key.

Parameter	Description
`id`required path · integer	Series id.
`filter[state]` query · string	Stored state — unused, consumed, active, exhausted, revoked.
`filter[disposition]` query · string	Who holds the card, which is orthogonal to state.
`filter[has_customer]` query · boolean	Cards linked to a subscriber.

Parameter	Description
`id`required path · integer	Series id.
`count`required body · integer	How many cards to move.
`from_manager_id`required body · integer	The current holder.
`to_manager_id`required body · integer	The receiving reseller.
`unit_price`required body · number	Price per card. Required, never defaulted to zero.
`request_id`required body · string	Idempotency key.

Parameter	Description
`id`required path · integer	Series id.
`card_id_range`required body · object	The inclusive id range to move.
`unit_price`required body · number	Price per card. Required.
`request_id`required body · string	Idempotency key.

API reference

Users

Tickets

NAS

Portal

User

Tools

Monitoring

Managers

Public

Card Batches

Profiles

Auth

Reports

Studio

Payments

Freezone

POS

Sessions

Cards

Developer

Devgw

Hotspot

Card Templates

IP Pools

Shop

Webhooks

Addons

Dashboards

Forms

Sas4

Backup

Control

Exports

Notification Outbox

Notification Rules

Roles

Branding

Email Templates

Import

Notification Channels

Trash

Groups

Telegram

Console Sessions

Notification Templates

Pricing

Settings

Setup

Telegram Manager

Billing

Logs

License

Notification Event Options

Notification Events

Permissions

Postpaid

System

Tenants

Written to be read by machines too

Try it on your own network.

Parameter	Description
`filter[type]` query · enum	prepaid, postpaid, fup, extension or addon.
`filter[status]` query · string	Plan status.
`filter[assignable]` query · boolean	Only plans this caller may bind to a subscriber. Narrower than visibility, and the right filter behind a plan picker.
`filter[allowed_services]` query · enum	ppp, hotspot or both.
`filter[show_in_ucp]` query · boolean	Plans the subscriber portal offers for self-service renewal.
`filter[private]` query · boolean	Plans restricted to an explicit manager allow-list.
`filter[has_fup_chain]` query · boolean	Plans that fall back to another plan on expiry or quota exhaustion.
`sort` query · string	id, created_at, name, type or status. Defaults to name ascending.

Parameter	Description
`name`required body · string	Display name.
`type`required body · enum	prepaid, postpaid, fup, extension or addon.
`base_fee` body · number	Wholesale price to the reseller, major units.
`end_user_price` body · number	Retail price, major units.
`expiration_value` body · integer	Period length, paired with expiration_unit.
`expiration_unit` body · enum	hours, days or months.

Parameter	Description
`email`required body · string	Email or username.
`password`required body · string	The manager's password.
`totp_code` body · string	Six-digit code or a recovery code. Sent on the second attempt, after the first returns mfa_required.
`tenant_slug` body · string	Honoured only when the host carries no tenant. Ignored outright on a tenant subdomain.
`refresh` body · boolean	Opt in to the refresh-token flow. Omitting it returns one long-lived token and no refresh fields at all.

Parameter	Description
`q` query · string	Searches username, first and last name, framed IP, device MAC and NAS name.
`filter[nas_id]` query · integer	Sessions on one registered NAS.
`filter[kind]` query · enum	subscriber, guest, voucher or unknown.
`filter[has_ip]` query · boolean	Sessions that were assigned a framed IP.
`filter[duration_band]` query · string	Duration bucket. The value "stale" means no accounting update for longer than the tenant's idle window, which is the practical definition of a ghost session.
`filter[expired]` query · boolean	Sessions whose owner's subscription has run out but who are still connected.

Parameter	Description
`code`required body · string	The plaintext card code.
`user_id`required body · integer	The subscriber to credit.
`request_id`required body · string	Idempotency key.

Parameter	Description
`kind`required query · enum	code, serial or username.
`keyword`required query · string	The value to match. A code is normalised first, so separators and mixed case still resolve.

Parameter	Description
`filter[endpoint_id]` query · integer	Narrow to one endpoint. Also accepted as a bare endpoint_id parameter.
`filter[state]` query · enum	queued, sending, sent, failed or dead. An unknown value is a 400.
`sort` query · string	queued_at, state, attempts or id. Defaults to queued_at descending.

Parameter	Description
`name`required body · string	A label for the endpoint.
`url`required body · string	Where deliveries are POSTed. Validated on save.
`events` body · array	Event keys from the catalogue. Ignored when all_events is true.
`all_events` body · boolean	Subscribe to every event, including ones added in later releases.
`enabled` body · boolean	Defaults to true on create.

Parameter	Description
`filter[status]` query · string	Job status.
`filter[format]` query · enum	csv or xlsx.
`filter[target_table]` query · string	One dataset key. The special value "reports" expands to every report dataset rather than matching exactly.

Parameter	Description
`target_table`required body · string	A dataset key from the datasets endpoint.
`format` body · enum	csv or xlsx. Defaults to xlsx.
`params` body · object	Dataset-specific filters, in the same shape that dataset's list endpoint accepts.
`request_id` body · string	Optional idempotency key. Blank stays blank and means no deduplication at all — supply your own if a retry must not queue a second job.