文档中心

TRAE CN

部门管理

按关键字搜索部门

按关键字搜索企业内的部门。支持不区分大小写的模糊匹配。

所需权限

departments:read

请求说明

请求方式：GET

请求地址：{域名}/openapi/v1/departments/search

请求参数

请求头参数

Header 参数	是否必填	描述
Authorization	是	固定取值为 Bearer {access_token}。关于如何获取访问令牌，参考鉴权。

查询参数

参数	类型	是否必填	默认值	描述
keyword	string	是	-	搜索关键字，最长为 64 个 Unicode 字符。 keyword= 表示显式空字符串，请求成功并返回空列表；非空值按部门名称和完整路径做不区分大小写的模糊匹配。
page	int	否	1	需返回的页数。
page_size	int	否	100	每页返回的部门数量。取值范围：[1, 500]。

响应参数

该接口独有的响应参数如下，参数位于 data 中。通用响应参数参考此文档。

items	array	部门列表。
items[].department_id	string	部门的 ID。
items[].parent_department_id	string	部门直属的父部门的 ID，根部门为 "0"。
items[].name	string	部门的名称。
items[].full_path	string	部门的完整归属路径。各级部门名称以 / 分隔。
items[].depth	int	部门的层级深度。根部门为 0。

示例

请求示例

curl -X GET "${HOST}/openapi/v1/departments/search?keyword=%E7%A0%94%E5%8F%91&page=1" \​
  -H "Authorization: Bearer ${ACCESS_TOKEN}"​

响应示例

{​
  "code": 0,​
  "message": "success",​
  "request_id": "req_xxx",​
  "data": {​
    "items": [​
      {​
        "department_id": "20001",​
        "parent_department_id": "90001",​
        "name": "研发一部",​
        "full_path": "示例企业/研发一部",​
        "depth": 1​
      }​
    ],​
    "pagination": {​
      "page": 1,​
      "page_size": 100,​
      "total": 1,​
      "total_pages": 1​
    }​
  }​
}​

错误码

若该接口的请求返回错误码，参考错误码文档进行排查。

最近更新时间：2026.10.10 17:34:32

这个页面对您有帮助吗？

有用

无用