User

The User object is supported by the MiRTA PBX OpenAPI endpoint. This object is managed at system scope and requires a global API key.

Object Summary

Property	Value
Object	user
Primary path	/users
ID field	us_id
Label field	us_username
Primary source table	us_users
Required on create	us_username
Path aliases	/user, /users, /nuser, /nusers, /us_user, /us_users

Endpoint Patterns

Action	Example pattern
List	GET https://pbx.example.com/pbx/openapi.php/users
Get by ID	GET https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID
Create	POST https://pbx.example.com/pbx/openapi.php/users
Update	PATCH https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID
Delete	DELETE https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID

Accepted Field Aliases

Request field	Source field
username	us_username
name	us_username
description	us_description
email	us_email
profile_id	us_up_id
userprofile_id	us_up_id
password	us_password
use_ldap	us_useldap
ip_filter	us_ipfilter
two_factor_type	us_2fatype
never_expire	us_neverexpire
dynamic_ip	us_dynamicip

Examples

List Users

Returns the users visible to the key and scope.

curl -H "X-API-Key: GLOBAL_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/users"

Get User

Reads one object by its internal ID.

curl -H "X-API-Key: GLOBAL_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID"

Create User

Creates a new object. Use the short aliases shown above or the source field names.

curl -X POST \
  -H "X-API-Key: GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "docs-api-user",
  "description": "Documentation API user",
  "email": "docs-api-user@example.com",
  "profile_id": 2,
  "password": "change-this-password",
  "tenant_ids": [
    1
  ]
}' \
  "https://pbx.example.com/pbx/openapi.php/users"

Edit User

Updates only the supplied fields.

curl -X PATCH \
  -H "X-API-Key: GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "docs-api-user-updated@example.com",
  "force_change": true
}' \
  "https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID"

Delete User

Deletes the object. Check references before deleting configuration used by routing or reporting.

curl -X DELETE \
  -H "X-API-Key: GLOBAL_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID"

User Tenant and Routing Profile Relations

Replaces the user tenant, routing profile, and allowed profile relations with the supplied IDs.

curl -X PATCH \
  -H "X-API-Key: GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_ids": [
    1
  ],
  "routingprofile_ids": [
    3
  ],
  "allowed_userprofile_ids": [
    2
  ]
}' \
  "https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID"

User Object Restrictions

Restricts the user to specific queues, extensions, or providers.

curl -X PATCH \
  -H "X-API-Key: GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "queue_restrictions": [
    12
  ],
  "extension_restrictions": [
    45
  ],
  "provider_restrictions": [
    7
  ]
}' \
  "https://pbx.example.com/pbx/openapi.php/users/OBJECT_ID"

Common Errors

Error	Meaning
missing_api_key	No API key was supplied in the query string, X-API-Key, or bearer token.
invalid_api_key	The supplied key does not match the tenant or global API key.
tenant_required	A tenant code is required for tenant-scoped writes or tenant-key reads.
read_only_api_key	The key can read data but cannot create, update, or delete objects.
missing_required_field	A required create field is missing.