飞书开放平台 Server API 文档

主题

获取单个部门信息 ​

调用该接口获取单个部门信息，包括部门名称、ID、父部门、负责人、状态以及成员个数等。

注意事项 ​

使用不同身份调用本接口时，需要注意不同身份所需的不同权限范围。具体说明如下：

  • 当你使用应用身份（tenant_access_token）调用本接口时，应用的通讯录权限范围内需要包含当前被查询的部门。如果需要查询根部门信息，则应用的通讯录权限范围需设置为 全部成员。了解权限范围参见权限范围资源介绍。
  • 当你使用用户身份（user_access_token）调用本接口时，需要确保该用户身份拥有待查询部门的可见性。如果需要查询根部门信息，则用户需要可见所有人。用户的组织架构可见范围需要由企业管理员在管理后台 > 安全 > 成员权限 > 组织架构可见范围 内调整。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/contact/v3/departments/:department_id
HTTP MethodGET
接口频率限制特殊频控
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可contact:contact.base:readonly 获取通讯录基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:department.base:readonly 获取部门基础信息 contact:user.employee_id:readonly 获取用户 user ID contact:department.hrbp:readonly 查询部门 HRBP 信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数 ​

名称类型描述
department_idstring部门 ID，ID 类型需要与查询参数 department_id_type 的取值保持一致。ID 获取方式说明：
- 调用创建部门接口后，可从返回结果中获取到部门 ID 信息。 - 部门 API 提供了多种获取其他部门 ID 的方式，如获取子部门列表、获取父部门信息、搜索部门，你可以选择合适的 API 进行查询。
示例值："D096"
数据校验规则：
- 最大长度：64 字符 - 正则校验：^[a-zA-Z0-9][a-zA-Z0-9_\-@.]{0,63}$

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。
示例值：open_department_id
可选值有：
- department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。
默认值：open_department_id

Go 请求示例

go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewGetDepartmentReqBuilder().
		DepartmentId(`D096`).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Get(context.Background(), req)
}

Java 请求示例

java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {

    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        GetDepartmentReq req = GetDepartmentReq.newBuilder()
                .departmentId("D096")
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .build();

        // 发起请求
        GetDepartmentResp resp = client.contact().department().get(req, RequestOptions.newBuilder().build());
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ departmentdepartment部门信息。
    └ namestring部门名称。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ i18n_namedepartment_i18n_name部门名称的国际化配置。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ zh_cnstring部门的中文名。
      └ ja_jpstring部门的日文名。
      └ en_usstring部门的英文名。
    └ parent_department_idstring父部门的部门 ID。
- ID 类型与查询参数的 department_id_type 取值保持一致。 - 当父部门为根部门时，该参数值为 0。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ department_idstring自定义部门 ID。后续可以使用该 ID 删除、修改、查询部门信息。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ open_department_idstring部门的 open_department_id，由系统自动生成。后续可以使用该 ID 删除、修改、查询部门信息。
    └ leader_user_idstring部门主管的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ chat_idstring部门群的群 ID。后续可以使用获取群信息，获取群的详细信息。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ orderstring部门的排序，即部门在其同级部门的展示顺序。取值越小排序越靠前。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ unit_idsstring\[\]部门绑定的单位自定义 ID 列表，当前只支持一个。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ member_countint当前部门及其下属部门的用户（包含部门负责人）个数。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ statusdepartment_status部门状态。
字段权限要求（满足任一）： contact:department.base:readonly 获取部门基础信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ is_deletedboolean是否被删除。
可能值有：
- true：是 - false：否
    └ leadersdepartmentLeader\[\]部门负责人信息。
      └ leaderTypeint负责人类型。
可选值有：
- 1: 主负责人 - 2: 副负责人
      └ leaderIDstring负责人的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ group_chat_employee_typesint\[\]部门群的人员类型限制。人员类型的可能值如下：
- 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问
如果是自定义人员类型，则会返回对应的编号。你可以调用查询人员类型接口，获取相应编号（enum_value）对应的自定义人员类型信息。
    └ department_hrbpsstring\[\]部门 HRBP 的用户 ID 列表。 ID 类型与查询参数 user_id_type 的取值保持一致。
字段权限要求： contact:department.hrbp:readonly 查询部门 HRBP 信息
    └ primary_member_countint当前部门及其下属部门的主属成员（即成员的主部门为当前部门）的数量。
字段权限要求（满足任一）： contact:department.organize:readonly 获取通讯录部门组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "department": {
            "name": "DemoName",
            "i18n_name": {
                "zh_cn": "Demo名称",
                "ja_jp": "デモ名",
                "en_us": "Demo Name"
            },
            "parent_department_id": "D067",
            "department_id": "D096",
            "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
            "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "chat_id": "oc_5ad11d72b830411d72b836c20",
            "order": "100",
            "unit_ids": [
                "custom_unit_id"
            ],
            "member_count": 100,
            "status": {
                "is_deleted": false
            },
            "leaders": [
                {
                    "leaderType": 1,
                    "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                }
            ],
            "group_chat_employee_types": [
                1
            ],
            "department_hrbps": [
                "ou_7dab8a3d3cdcc9da365777c7ad535d62"
            ],
            "primary_member_count": 100
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
40040001param error参数错误。请检查请求时传入的参数是否填写有误。
40043010big dept forbid recursion error超大部门不允许进行查询。
40040003internal error内部错误，请获取请求的 X-Request-Id，并向技术支持进行反馈。
40340004no dept authority error当前操作涉及的部门，需在应用通讯录权限范围中，了解更多可参见权限范围资源介绍。
40040008dept Info is null error部门的信息不能为空。
40142008tenant id is invalid error租户身份无效。请求时，请确保设置的请求头 Authorization 与待操作资源同属一个租户下。
40040015department not exist部门不存在。请改为正确的 department_id 参数值并重试。

更多错误码信息，参见通用错误码。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有