Create a subscriber

POST /api/v1/users prm_users_create

Creates the account and its identity only. It does not activate a plan, take money or grant quota — binding profile_id here is metadata. Use the activation endpoint for the paid part.

debt_limit is tri-state and the two falsy values mean opposite things. Omitted or null is unlimited credit; 0 is no credit at all. Sending 0 to mean "no opinion" silently blocks every future debit.

At a glance

Authentication: Staff token or session
Requires permission: prm_users_create Create users
Rate limit: t_mutate

Parameters

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.

Errors

Code	When it is returned
`ERR_VALIDATION`400	username or password missing, bad expiration, unassignable or inactive plan, unknown parent or group
`ERR_CONFLICT`409	the username is taken in this tenant, or the licence subscriber cap is reached
`ERR_LICENSE_BLOCKED`403	the tenant's licence has expired

Request

curl -X POST "$BASE/api/v1/users" \
  -H "Authorization: Bearer $XR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "ahmed",
  "password": "s3cret-pass",
  "profile_id": 7,
  "parent_id": 41,
  "email": "ahmed@example.test",
  "phone": "+201000000000",
  "enabled": true,
  "debt_limit": 0
}'

Response 201 Created

{
  "data": {
    "id": 4712,
    "tenant_id": 12,
    "username": "ahmed",
    "enabled": true,
    "profile_id": 7,
    "parent_id": 41,
    "balance": 0.00,
    "debt": 0.00,
    "created_at": "2026-09-20 09:14:55"
  }
}

BASE is your tenant host: the same address you sign in on.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us