User Management

The Users API allows creating, updating, listing, bulk-importing, deleting, and clearing user profiles across edge devices.

Endpoints Overview

Method	Endpoint	Description
GET	/api/users	Retrieve a paginated list of user records
POST	/api/users	Create a new user or update an existing user
GET	/api/users/{pin}	Retrieve a single user profile by PIN
DELETE	/api/users/{pin}	Delete a user by PIN and sync with devices
POST	/api/users/import	Bulk import or update multiple users
DELETE	/api/users/clear	Delete specific or all users from location

---

List Users

GET /api/users

Retrieve a paginated list of user records assigned to the authenticated location.

Query Parameters

Parameter	Type	Required	Default	Options / Enums	Description
page	Integer	No	1	>= 1	Page number.
limit	Integer	No	15	1 to 100	Number of items per page.
search	String	No	null	Any string	Search by first_name, last_name, or pin.
privilege	Integer	No	null	0 (User), 2 (Enroller), 6 (Manager), 14 (Super Admin)	Filter by user privilege level.
is_active	Boolean	No	null	true, false	Filter by active status.
include	String	No	null	biometrics	Pass "biometrics" to include enrolled biometric templates.

---

Response Attributes

Pagination Response Wrap

Attribute	Type	Description
data	Array[UserResponse]	Array of user records.
total	Integer	Total count of filtered users.
page	Integer	Current page index.
limit	Integer	Limit per page.
total_pages	Integer	Calculated total page count.
has_next	Boolean	Next page availability.
has_prev	Boolean	Previous page availability.

UserResponse Attributes

Attribute	Type	Options / Enums	Description
id	Integer	None	Unique internal user database ID.
location_id	Integer	None	Location ID.
location	LocationBasic | Null	None	Basic location summary object (id, name).
pin	Integer	1 to 99999999	User PIN / Badge ID.
first_name	String | Null	None	User first name.
last_name	String | Null	None	User last name.
card_no	String | Null	None	RFID / Proximity card number string.
password	Integer | Null	Numeric	Device keypad verification password.
is_active	Boolean	true, false	Active status flag.
start_time	String (ISO 8601) | Null	Datetime / Date	Access validity start date/time.
end_time	String (ISO 8601) | Null	Datetime / Date	Access validity expiration date/time.
privilege	Integer	0 (User), 2 (Enroller), 6 (Manager), 14 (Super Admin)	Device privilege level.
group	Integer	0 to 99	Access control group.
super_authorize	Integer	0, 1	Super authorize permissions flag.
has_biometric	Boolean	true, false	Indicates whether enrolled fingerprint or face templates exist.
biometric_templates	Array[BiometricTemplateResponse] | Null	None	Detailed template list (included if include=biometrics).
created_at	String (ISO 8601)	None	Timestamp when created.
updated_at	String (ISO 8601) | Null	None	Timestamp when last updated.

---

Response Example

200 OK

{
  "data": [
    {
      "id": 84,
      "location_id": 1,
      "location": {
        "id": 1,
        "name": "Headquarters Office"
      },
      "pin": 10042,
      "first_name": "John",
      "last_name": "Doe",
      "card_no": "0001234567",
      "password": 1234,
      "is_active": true,
      "start_time": null,
      "end_time": null,
      "privilege": 0,
      "group": 0,
      "super_authorize": 0,
      "has_biometric": true,
      "biometric_templates": null,
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-08-26T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 15,
  "total_pages": 1,
  "has_next": false,
  "has_prev": false
}

---

Create or Update User

POST /api/users

Create a new user or update an existing user identified by PIN. Automatically generates device sync commands.

Request Body Parameters (TenantUserCreate)

Parameter	Type	Required	Default	Options / Enums	Description
pin	Integer	Yes	None	1 to 99999999	User PIN / Badge number.
first_name	String	Required for NEW users	null	Any text	User first name.
last_name	String	No	null	Any text	User last name.
card_no	String	No	null	Any text	Proximity card number.
password	Integer	No	null	Numeric	Keypad password.
is_active	Boolean	No	true	true, false	Active status.
start_time	String	No	null	YYYY-MM-DD or ISO Datetime	Access start date.
end_time	String	No	null	YYYY-MM-DD or ISO Datetime	Access expiration date.
privilege	Integer	No	0	0 (User), 2 (Enroller), 6 (Manager), 14 (Super Admin)	Device privilege level.
group	Integer	No	0	0 to 99	Access control group.
super_authorize	Integer	No	0	0, 1	Super authorization flag.

---

Response Attributes

Returns the created/updated UserResponse object.

---

Response Example

Request Body

{
  "pin": 10042,
  "first_name": "John",
  "last_name": "Doe",
  "card_no": "0001234567",
  "password": 1234,
  "privilege": 0,
  "is_active": true
}

201 Created

{
  "id": 84,
  "location_id": 1,
  "location": {
    "id": 1,
    "name": "Headquarters Office"
  },
  "pin": 10042,
  "first_name": "John",
  "last_name": "Doe",
  "card_no": "0001234567",
  "password": 1234,
  "is_active": true,
  "start_time": null,
  "end_time": null,
  "privilege": 0,
  "group": 0,
  "super_authorize": 0,
  "has_biometric": false,
  "biometric_templates": null,
  "created_at": "2026-08-26T17:51:00Z",
  "updated_at": null
}

---

Get User Details

GET /api/users/{pin}

Retrieve single user profile by PIN.

Path Parameters

Parameter	Type	Required	Description
pin	Integer	Yes	User PIN number.

Query Parameters

Parameter	Type	Required	Default	Options	Description
include	String	No	null	biometrics	Include enrolled biometric templates.

---

Response Attributes

Returns UserResponse object.

---

Response Example

200 OK (with biometrics)

{
  "id": 84,
  "location_id": 1,
  "pin": 10042,
  "first_name": "John",
  "last_name": "Doe",
  "card_no": "0001234567",
  "password": 1234,
  "is_active": true,
  "start_time": null,
  "end_time": null,
  "privilege": 0,
  "group": 0,
  "super_authorize": 0,
  "has_biometric": true,
  "created_at": "2026-08-26T17:51:00Z",
  "updated_at": null,
  "biometric_templates": [
    {
      "id": 102,
      "user_pin": 10042,
      "bio_type": "fingerprint",
      "finger_id": 1,
      "valid": 1,
      "created_at": "2026-08-26T17:52:00Z"
    }
  ]
}

---

Delete User

DELETE /api/users/{pin}

Delete user by PIN and dispatch delete user commands to connected devices.

Path Parameters

Parameter	Type	Required	Description
pin	Integer	Yes	User PIN number to delete.

---

Response Example

204 No Content

{}

---

Bulk Import Users

POST /api/users/import

Import or update multiple users in a single request with batched device synchronization.

Request Body Parameters

Array of user objects (List[dict]).

Parameter	Type	Required	Default	Description
pin	Integer | String	Yes	None	User PIN number.
first_name	String	Yes (for new users)	None	User first name.
last_name	String	No	null	User last name.
card_no	String	No	null	Card number.
password	Integer	No	null	Keypad password.
is_active	Boolean	No	true	Active status.
privilege	Integer	No	0	Privilege level (0, 2, 6, 14).

---

Response Attributes

Attribute	Type	Description
message	String	Summary message string.
processed_count	Integer	Total number of successfully processed users.
error_count	Integer	Total number of errors encountered.
processed_users	Array[UserResponse]	Array of processed UserResponse objects.
errors	Array[Object]	Array of error objects containing user_data and error details.

---

Response Example

Request Body

[
  {
    "pin": 10042,
    "first_name": "John",
    "last_name": "Doe",
    "card_no": "0001234567",
    "password": 1234,
    "privilege": 0
  },
  {
    "pin": 10043,
    "first_name": "Jane",
    "last_name": "Smith",
    "privilege": 0
  }
]

200 OK

{
  "message": "Bulk import completed. 2 users processed, 0 errors.",
  "processed_count": 2,
  "error_count": 0,
  "processed_users": [
    {
      "id": 84,
      "location_id": 1,
      "pin": 10042,
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "privilege": 0
    },
    {
      "id": 85,
      "location_id": 1,
      "pin": 10043,
      "first_name": "Jane",
      "last_name": "Smith",
      "is_active": true,
      "privilege": 0
    }
  ],
  "errors": []
}

---

Clear Users

DELETE /api/users/clear

Delete specific users (by array of PINs) or ALL users from location and create delete device commands.

Request Body Parameters (UserClearRequest)

Parameter	Type	Required	Default	Description
pins	Array[Integer] | Null	No	null	Array of user PIN numbers to clear. If omitted or null, ALL users in location are cleared.

---

Response Attributes

Attribute	Type	Description
message	String	Execution outcome message.
users_deleted	Integer	Number of users soft-deleted/deactivated.
devices_affected	Integer	Number of edge devices targeted for command push.
commands_created	Integer	Number of device delete commands created.

---

Response Example

Request Body

{
  "pins": [10042, 10043]
}

200 OK

{
  "message": "Cleared 2 users and created 6 delete commands for 3 devices",
  "users_deleted": 2,
  "devices_affected": 3,
  "commands_created": 6
}