Users

5/8/2026

blog.summarize

blog.share_blog

Users API

API dùng để xem danh sách, xem chi tiết, mời, cập nhật và xóa người dùng trong workspace.

Xác thực

Tất cả request yêu cầu header:

Authorization: Bearer {tokenId}-{secretToken}

Với request có JSON body, gửi thêm:

Content-Type: application/json

1. Xem danh sách người dùng

Endpoint: POST /bapi/v1/users/list

Request Body

{
  "page": 1,
  "limit": 20,
  "status": "ACTIVE,INVITED",
  "search": "an@company.com",
  "order": "last_join_time",
  "sort": "desc"
}

Trường	Kiểu	Bắt buộc	Mô tả
`page`	Integer	Không	Trang bắt đầu lấy dữ liệu. Mặc định: `1`
`limit`	Integer	Không	Số người dùng tối đa mỗi lần lấy. Mặc định: `20`, tối đa: `100`
`status`	String	Không	Một hoặc nhiều trạng thái phân tách bằng dấu phẩy: `ACTIVE`, `SUSPENDED`, `INVITED`, `DEACTIVATED`
`search`	String	Không	Tìm gần đúng theo họ tên hoặc email
`name`	String	Không	Tìm gần đúng theo họ tên hiển thị
`full_name`	String	Không	Tìm gần đúng theo họ tên đầy đủ
`role`	String	Không	Một hoặc nhiều ID vai trò phân tách bằng dấu phẩy
`department`	String	Không	Một hoặc nhiều giá trị phòng ban phân tách bằng dấu phẩy
`position`	String	Không	Một hoặc nhiều giá trị vị trí công việc phân tách bằng dấu phẩy
`department_ids`	String	Không	Một hoặc nhiều ID phòng ban phân tách bằng dấu phẩy
`position_ids`	String	Không	Một hoặc nhiều ID vị trí công việc phân tách bằng dấu phẩy
`license`	String	Không	Một hoặc nhiều loại giấy phép phân tách bằng dấu phẩy
`last_join_time`	String	Không	Khoảng thời gian tham gia dạng `{from},{to}`, dùng timestamp mili giây. Có thể bỏ trống một đầu
`ids`	String	Không	Chỉ lấy các ID người dùng, phân tách bằng dấu phẩy
`ignore_ids`	String	Không	Loại trừ các ID người dùng, phân tách bằng dấu phẩy
`search_after`	String	Không	Con trỏ lấy trang tiếp theo, được tạo từ `meta.search_after` của response trước
`group_by`	String	Không	Nhóm kết quả theo `status`, `gender`, `license` hoặc `work_type`
`show_detail_on_record`	Boolean	Không	`true` để trả về dữ liệu chi tiết hơn cho từng người dùng
`order`	String	Không	Trường sắp xếp: `full_name`, `last_name`, `first_name`, `name`, `created`, `updated`, `last_join_time`, `account_email` hoặc `status`. Mặc định: `updated`
`sort`	String	Không	Chiều sắp xếp: `asc` hoặc `desc`. Mặc định: `desc`

Quan trọng: Trạng thái lời mời là INVITED, không phải INVITE. Gửi giá trị không hợp lệ sẽ trả về lỗi meta.status = "invalid".

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/users/list' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "limit": 20,
    "status": "ACTIVE,INVITED",
    "search": "",
    "order": "last_join_time",
    "sort": "desc"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Success",
  "data": [
    {
      "id": "USR4J8H2Q7MN",
      "workspace_id": "WS8M3Q7D2K1P",
      "account_id": "ACC5F9T1L3RX",
      "account_email": "an@company.com",
      "first_name": "An",
      "last_name": "Nguyễn Văn",
      "_full_name": "An Nguyễn Văn",
      "status": "ACTIVE",
      "license": "FULL",
      "role": ["RO6P2N1K9X4A"],
      "last_join_time": 1785888000000,
      "created": 1785801600000,
      "updated": 1785891600000
    }
  ],
  "meta": {
    "total": 1,
    "t2": 1,
    "search_after": [1785891600000, "USR4J8H2Q7MN"]
  },
  "requestId": "5f8f521d-00029447-96e276bd-6df7-48d4-8c33-bf9c63ea46c2"
}

Để lấy trang tiếp theo, chuyển meta.search_after thành JSON string và gửi lại ở search_after cùng bộ lọc, limit, order và sort không đổi. Khi dùng group_by, data là object có các nhóm thay vì một mảng phẳng.

2. Xem chi tiết người dùng

Endpoint: POST /bapi/v1/users/view

Request Body

{
  "id": "USR4J8H2Q7MN"
}

Trường	Kiểu	Bắt buộc	Mô tả
`id`	String	Có	ID người dùng trả về từ API danh sách hoặc API mời

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/users/view' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "USR4J8H2Q7MN"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": {
    "id": "USR4J8H2Q7MN",
    "workspace_id": "WS8M3Q7D2K1P",
    "account_id": "ACC5F9T1L3RX",
    "account_email": "an@company.com",
    "first_name": "An",
    "last_name": "Nguyễn Văn",
    "_full_name": "An Nguyễn Văn",
    "status": "ACTIVE",
    "license": "FULL",
    "role": ["RO6P2N1K9X4A"],
    "phone_numbers": ["0901234567"],
    "language": "vi",
    "timezone": "Asia/Ho_Chi_Minh",
    "last_join_time": 1785888000000,
    "created": 1785801600000,
    "updated": 1785891600000
  },
  "requestId": "5f8f521d-00029447-a48258be-137e-4dc5-a0b6-567b530d18f9"
}

Ngoài các trường chung ở trên, data có thể chứa các trường hồ sơ được cấu hình riêng cho workspace.

3. Mời người dùng vào workspace

Endpoint: POST /bapi/v1/users

API tạo người dùng bằng cách gửi lời mời tới địa chỉ email được cung cấp.

Request Body

{
  "account_email": "an@company.com",
  "first_name": "An",
  "last_name": "Nguyễn Văn",
  "license": "FULL",
  "role": ["RO6P2N1K9X4A"],
  "_jobs": [
    {
      "department_id": "DEP7C2M9Q4LK",
      "position_id": "POS3V8N1F6TR",
      "is_primary": true
    }
  ],
  "_apps": []
}

Trường	Kiểu	Bắt buộc	Mô tả
`account_email`	String	Có	Email nhận lời mời, tối đa 100 ký tự; email phải hợp lệ và chưa được sử dụng trong workspace
`first_name`	String	Có	Tên, tối đa 100 ký tự
`last_name`	String/null	Không	Họ và tên đệm, tối đa 100 ký tự
`license`	String	Có	Loại giấy phép; dùng giá trị được workspace hỗ trợ, ví dụ `FULL`
`role`	Array[String]	Có	Ít nhất một ID vai trò có thể gán
`_jobs`	Array	Không	Danh sách phòng ban và vị trí công việc
`_apps`	Array[String]	Không	Danh sách ID ứng dụng được gắn với lời mời. Mặc định: `[]`

Mỗi phần tử _jobs gồm:

Trường	Kiểu	Bắt buộc	Mô tả
`department_id`	String	Có	ID phòng ban
`position_id`	String	Có	ID vị trí thuộc phòng ban
`is_primary`	Boolean	Không	`true` nếu đây là công việc chính
`level`	Integer	Không	Cấp độ công việc. Mặc định: `0`

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/users' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_email": "an@company.com",
    "first_name": "An",
    "last_name": "Nguyễn Văn",
    "license": "FULL",
    "role": ["RO6P2N1K9X4A"],
    "_jobs": [
      {
        "department_id": "DEP7C2M9Q4LK",
        "position_id": "POS3V8N1F6TR",
        "is_primary": true
      }
    ],
    "_apps": []
  }'

Response thành công (201)

{
  "r": 0,
  "msg": "Successful",
  "data": {
    "id": "USR4J8H2Q7MN",
    "account_email": "an@company.com",
    "first_name": "An",
    "last_name": "Nguyễn Văn",
    "status": "INVITED",
    "created": 1785888000000,
    "updated": 1785888000000
  },
  "requestId": "5f8f521d-00029447-e9085037-8c08-4dc9-bd76-79e9eaa39e31"
}

Lời mời có hiệu lực trong 24 giờ. Không nên gọi lại API tạo để gửi lại một lời mời còn hiệu lực.

4. Cập nhật người dùng

Endpoint: PUT /bapi/v1/users/{user_id}

Path Parameters

Trường	Kiểu	Bắt buộc	Mô tả
`user_id`	String	Có	ID người dùng cần cập nhật

Request Body

{
  "first_name": "An",
  "last_name": "Nguyễn",
  "phone_numbers": ["0901234567"]
}

Trường	Kiểu	Bắt buộc	Mô tả
`first_name`	String	Có	Tên, tối đa 100 ký tự. Phải gửi trong mọi request cập nhật
`last_name`	String/null	Không	Họ và tên đệm, tối đa 100 ký tự
`phone_numbers`	Array[String]/null	Không	Danh sách số điện thoại
`setting`	Object/null	Không	Cài đặt người dùng được hỗ trợ

account_email không được thay đổi qua API này. Nếu có gửi, giá trị này vẫn được giữ nguyên.

Ví dụ cURL

curl --location --request PUT 'https://{workspace-domain}/bapi/v1/users/USR4J8H2Q7MN' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "An",
    "last_name": "Nguyễn",
    "phone_numbers": ["0901234567"]
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": {
    "first_name": "An",
    "last_name": "Nguyễn",
    "_full_name": "Nguyễn An",
    "phone_numbers": ["0901234567"],
    "status": null,
    "updated": "1785924036927"
  },
  "requestId": "5f8f521d-00029447-9f98afe3-ae86-4a2f-9db0-d68c08652575"
}

data là object kết quả cập nhật rút gọn. Object này có thể không có id, account_email, license hoặc role, và status có thể là null. Không dùng response update làm dữ liệu hồ sơ đầy đủ; gọi API xem chi tiết với user_id để lấy trạng thái mới nhất.

5. Xóa người dùng khỏi workspace

Endpoint: POST /bapi/v1/users/delete

Request Body

{
  "workspace_account_ids": ["USR4J8H2Q7MN"],
  "is_delete_personnel": false
}

Trường	Kiểu	Bắt buộc	Mô tả
`workspace_account_ids`	Array[String]	Có	Danh sách ID người dùng trả về từ API danh sách hoặc chi tiết
`is_delete_personnel`	Boolean	Không	`false`: chỉ xóa quyền truy cập workspace và giữ hồ sơ; `true`: đánh dấu xóa cả hồ sơ liên quan. Mặc định: `false`

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/users/delete' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspace_account_ids": ["USR4J8H2Q7MN"],
    "is_delete_personnel": false
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": null,
  "requestId": "5f8f521d-00029447-d9f642bf-1594-44a0-a696-d4ddd15fd480"
}

Không thể xóa chính người dùng đang gọi API hoặc xóa người quản trị cao nhất cuối cùng của workspace.

Khi is_delete_personnel = true, hồ sơ được đánh dấu DELETED thay vì biến mất ngay khỏi API. Gọi API xem chi tiết bằng ID cũ vẫn có thể trả về status: "DELETED" và deleted: 1.

Các trường phổ biến của user resource

Trường	Kiểu	Mô tả
`id`	String	ID người dùng dùng cho API chi tiết, cập nhật và xóa
`workspace_id`	String	ID workspace
`account_id`	String/null	ID tài khoản sau khi người dùng chấp nhận lời mời
`account_email`	String	Email đăng nhập/nhận lời mời
`first_name`	String	Tên
`last_name`	String/null	Họ và tên đệm
`_full_name`	String	Họ tên hiển thị theo cấu hình workspace
`status`	String	`ACTIVE`, `SUSPENDED`, `INVITED`, `DEACTIVATED` hoặc `DELETED`
`license`	String/null	Loại giấy phép
`role`	Array/String/null	Một hoặc nhiều vai trò được gán
`last_join_time`	Long/null	Lần tham gia gần nhất, timestamp mili giây
`last_left_time`	Long/null	Lần rời gần nhất, timestamp mili giây
`created`	Long	Thời điểm tạo, timestamp mili giây
`updated`	Long	Thời điểm cập nhật gần nhất, timestamp mili giây

Để gán hoặc loại một vai trò, sử dụng id ở trên làm userId khi gọi POST /bapi/v1/roles/addAccount hoặc POST /bapi/v1/roles/removeAccount.

Quy ước response và lỗi

HTTP Status	Ý nghĩa
`200`	Xem danh sách, xem chi tiết, cập nhật hoặc xóa thành công
`201`	Gửi lời mời thành công
`400`	Lỗi nghiệp vụ hoặc validation (`r != 0`); chi tiết thường nằm trong `meta`
`401`	Bearer token bị thiếu, sai, hết hạn hoặc không hoạt động
`429`	Vượt giới hạn số lượng request
`500`	Lỗi không mong muốn

Các lỗi mời người dùng phổ biến trong meta.account_email:

Giá trị	Ý nghĩa
`unique`	Email đã có trong workspace
`suspended`	Người dùng đang bị tạm ngưng
`inactive`	Tài khoản chưa hoạt động
`deactivated`	Tài khoản đã bị vô hiệu hóa

Ghi chú

Users API sử dụng tên trường dạng snake_case trong request và user resource.
Các ID vai trò, phòng ban và vị trí phải thuộc cùng workspace.
Các timestamp dùng đơn vị mili giây.

blog.blogs_related

Users

Users API

Xác thực

1. Xem danh sách người dùng

Request Body

Ví dụ cURL

Response thành công (200)

2. Xem chi tiết người dùng

Request Body

Ví dụ cURL

Response thành công (200)

3. Mời người dùng vào workspace

Request Body

Ví dụ cURL

Response thành công (201)

4. Cập nhật người dùng

Path Parameters

Request Body

Ví dụ cURL

Response thành công (200)

5. Xóa người dùng khỏi workspace

Request Body

Ví dụ cURL

Response thành công (200)

Các trường phổ biến của user resource

Quy ước response và lỗi

Ghi chú

Số hóa và tự động hóa hoàn toàn công tác vận hành và quản trị doanh nghiệp với Cogover!