Personnels

5/8/2026

blog.summarize

blog.share_blog

Personnels API

API dùng để xem danh sách, xem chi tiết, tạo, cập nhật, xóa nhân sự và cập nhật phòng ban/vị trí của nhân sự trong workspace.

Xác thực

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

Authorization: Bearer {tokenId}-{secretToken}
Content-Type: application/json

1. Xem danh sách nhân sự

Endpoint: POST /bapi/v1/personnels/list

Request Body

{
  "page": 1,
  "limit": 20,
  "status": "ACTIVE",
  "name": "Nguyễn",
  "order": "name",
  "sort": "asc"
}

Trường	Kiểu	Bắt buộc	Mô tả
`page`	Integer	Không	Số trang, mặc định `1`
`limit`	Integer	Không	Số kết quả mỗi trang, mặc định `20`
`ids`	String/Array	Không	Một hoặc nhiều ID nhân sự
`ignore_ids`	String/Array	Không	Các ID cần loại khỏi kết quả
`name` / `full_name`	String	Không	Lọc theo tên
`status`	String	Không	Lọc theo trạng thái; nhiều giá trị dùng dấu phẩy
`role`	String	Không	Lọc theo vai trò
`department` / `department_ids`	String	Không	Lọc theo phòng ban
`position` / `position_ids`	String	Không	Lọc theo vị trí
`group_by`	String	Không	Nhóm kết quả theo trường được hỗ trợ
`search_after`	String/Array	Không	Giá trị phân trang nhận từ response trước
`order`	String	Không	Trường sắp xếp: `name`, `full_name`, `created`, `updated`, `last_join_time`, `email` hoặc `status`; mặc định `updated`
`sort`	String	Không	`asc` hoặc `desc`; mặc định `desc`

Ví dụ cURL

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

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": [
    {
      "id": "PERXUDUQFEKMEK",
      "first_name": "An",
      "last_name": "Nguyễn",
      "_full_name": "Nguyễn An",
      "status": "ACTIVE",
      "emails": ["an.nguyen@example.com"]
    }
  ],
  "meta": {"total": 1}
}

2. Xem chi tiết nhân sự

Endpoint: POST /bapi/v1/personnels/view

{"id":"PERXUDUQFEKMEK"}

id là ID nhân sự và là trường bắt buộc.

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

Response trả về một nhân sự trong trường data, bao gồm thông tin hồ sơ và danh sách phòng ban/vị trí mà người đó đang đảm nhiệm.

3. Tạo nhân sự

Endpoint: POST /bapi/v1/personnels

{
  "first_name": "An",
  "last_name": "Nguyễn",
  "emails": ["an.nguyen@example.com"],
  "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ự
`last_name`	String	Không	Họ và tên đệm, tối đa 100 ký tự
`emails`	Array[String]	Không	Danh sách email
`phone_numbers`	Array[String]	Không	Danh sách số điện thoại
`status`	String	Không	Trạng thái nhân sự
`role`	Array[String]	Không	Danh sách ID vai trò

Có thể gửi thêm các trường hồ sơ đã được cấu hình cho nhân sự trong workspace.

Response thành công có HTTP status 201 và ID nhân sự mới trong data.id.

4. Cập nhật nhân sự

Endpoint: PUT /bapi/v1/personnels/{id}

{
  "first_name": "Anh",
  "phone_numbers": ["0901234567"]
}

Chỉ cần gửi các trường muốn thay đổi. Không dùng API này để đổi phòng ban/vị trí; dùng mục 6.

5. Xóa nhân sự

Endpoint: POST /bapi/v1/personnels/delete

{
  "data": ["PERXUDUQFEKMEK", "PER4KJ9Q2MD7AN"]
}

data là mảng ID nhân sự, bắt buộc và không được rỗng.

6. Cập nhật phòng ban/vị trí cho nhân sự

Endpoint: POST /bapi/v1/personnels/departmentPosition

{
  "data": [
    {
      "department_id": "XSGDAFMQXEKUIV",
      "position_id": "POSDAFMQ8EKUI4",
      "level": 1,
      "is_primary": true,
      "personnel_id": "PERXUDUQFEKMEK"
    }
  ]
}

Trường	Kiểu	Bắt buộc	Mô tả
`data`	Array	Có	Danh sách thay đổi, không được rỗng
`data[].personnel_id`	String	Có	ID nhân sự
`data[].department_id`	String	Có	ID phòng ban
`data[].position_id`	String	Có	ID vị trí
`data[].level`	Number	Không	Cấp quản lý trong phòng ban
`data[].is_primary`	Boolean	Không	`true` nếu đây là phòng ban/vị trí chính
`data[].deleted`	Boolean	Không	Gửi `true` để loại nhân sự khỏi cặp phòng ban/vị trí này
`data[].id`	String	Không	ID quan hệ hiện có khi cập nhật hoặc xóa

Mỗi nhân sự chỉ được xuất hiện một lần cho cùng một phòng ban trong một request.

curl --location 'https://{workspace-domain}/bapi/v1/personnels/departmentPosition' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{"data":[{"department_id":"XSGDAFMQXEKUIV","position_id":"POSDAFMQ8EKUI4","level":1,"is_primary":true,"personnel_id":"PERXUDUQFEKMEK"}]}'

Lỗi thường gặp

HTTP status	Ý nghĩa
`400`	Lỗi nghiệp vụ hoặc dữ liệu không hợp lệ; chi tiết thường nằm trong `meta`
`401`	Thiếu hoặc sai thông tin xác thực
`429`	Vượt giới hạn request
`500`	Lỗi không mong muốn

blog.blogs_related