Users API

Manage users and their attributes via the API.

Endpoints Overview

Method	Endpoint	Description
GET	/v1/users	List users
GET	/v1/users/:id	Get single user
POST	/v1/users	Create user
PATCH	/v1/users/:id	Update user
DELETE	/v1/users/:id	Deactivate user

List Users

Request

GET /v1/users

Query Parameters

Parameter	Type	Description
role	string	Filter by role
status	string	active, inactive
groupId	string	Filter by group
isVip	boolean	Filter VIP users
search	string	Search by name/email
page	number	Page number
limit	number	Items per page

Example

curl -X GET "https://api.dzdesk.com/v1/users?role=agent&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "usr_123",
        "email": "john.doe@company.com",
        "name": "John Doe",
        "role": "agent",
        "status": "active",
        "isVip": false,
        "groups": [
          {
            "id": "grp_hardware",
            "name": "Hardware Support"
          }
        ],
        "createdAt": "2024-01-01T00:00:00Z",
        "lastLoginAt": "2024-01-15T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "pages": 3
    }
  }
}

Get Single User

Request

GET /v1/users/:id

Example

curl -X GET "https://api.dzdesk.com/v1/users/usr_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": "usr_123",
    "email": "john.doe@company.com",
    "name": "John Doe",
    "role": "agent",
    "status": "active",
    "isVip": false,
    "groups": [
      {
        "id": "grp_hardware",
        "name": "Hardware Support"
      },
      {
        "id": "grp_network",
        "name": "Network Support"
      }
    ],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-10T12:00:00Z",
    "lastLoginAt": "2024-01-15T09:00:00Z",
    "identityProvider": "azure_entra",
    "metadata": {
      "department": "IT",
      "location": "Istanbul"
    }
  }
}

Create User

Request

POST /v1/users

Body Parameters

Field	Type	Required	Description
email	string	Yes	User email
name	string	Yes	Display name
role	string	Yes	admin, agent, viewer
groups	array	No	Group IDs to add
isVip	boolean	No	VIP status

Example

curl -X POST "https://api.dzdesk.com/v1/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.user@company.com",
    "name": "New User",
    "role": "agent",
    "groups": ["grp_software"],
    "isVip": false
  }'

Response

{
  "success": true,
  "data": {
    "id": "usr_456",
    "email": "new.user@company.com",
    "name": "New User",
    "role": "agent",
    "status": "active",
    "createdAt": "2024-01-15T15:00:00Z"
  }
}

Update User

Request

PATCH /v1/users/:id

Body Parameters

Field	Type	Description
name	string	Updated name
role	string	New role
groups	array	Updated group list
isVip	boolean	VIP status
status	string	active, inactive

Example

curl -X PATCH "https://api.dzdesk.com/v1/users/usr_123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "isVip": true
  }'

Response

{
  "success": true,
  "data": {
    "id": "usr_123",
    "role": "admin",
    "isVip": true,
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}

Deactivate User

Request

DELETE /v1/users/:id

Example

curl -X DELETE "https://api.dzdesk.com/v1/users/usr_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": "usr_123",
    "status": "inactive",
    "deactivatedAt": "2024-01-15T17:00:00Z"
  }
}

Note: Users are deactivated, not deleted. History is preserved.

Groups Endpoints

List Groups

GET /v1/groups

Response

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "grp_hardware",
        "name": "Hardware Support",
        "description": "Physical equipment issues",
        "memberCount": 5
      }
    ]
  }
}

Get Group Members

GET /v1/groups/:id/members

Add User to Group

POST /v1/groups/:id/members

{
  "userId": "usr_123"
}

Remove User from Group

DELETE /v1/groups/:id/members/:userId

Current User

Get Current User

GET /v1/me

Returns the authenticated user's profile.

Response

{
  "success": true,
  "data": {
    "id": "usr_123",
    "email": "current.user@company.com",
    "name": "Current User",
    "role": "agent",
    "groups": [...],
    "permissions": [
      "requests:read",
      "requests:write"
    ]
  }
}

Role Values

Role	Description
admin	Full system access
agent	Standard operations
viewer	Read-only access

Status Values

Status	Description
active	Can log in
inactive	Cannot log in

Related Topics

• Authentication - API authentication
• Requests API - Request endpoints
• User & Group Management - Admin guide