飞书开放平台 Server API 文档

主题

获取部门列表 ​

本接口用于依据指定条件，批量获取符合条件的部门详情列表。

Tip: 注意：

  • 本接口支持tenant_access_token和user_access_token。
    • 使用tenant_access_token时，数据权限遵循应用的通讯录权限范围，返回的字段数据为应用有权限的字段。可以在开发者后台-应用详情-权限管理中查看通讯录授权范围。 > - 使用user_access_token时，默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可查看部门信息时，管理员管理范围取最大集。管理员权限可查看帮助中心文档： 管理员创建管理员角色及分配权限

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/directory/v1/departments/filter
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用directory:department:list 调用 API 获取部门列表
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 directory:department.base:read 查看部门基础信息 directory:department.count:read 查看部门成员与子部门计数 directory:department.custom_field:read 查看部门自定义字段信息 directory:department.data_source:read 查看部门数据来源 directory:department.department_path:read 查看部门路径信息 directory:department.external_id:read 查看部门自定义 ID directory:department.has_child:read 查看部门是否有子部门 directory:department.leader:read 查看部门负责人信息 directory:department.name:read 查看部门的名称 directory:department.order_weight:read 查看部门排序权重 directory:department.organization:read 查看部门组织架构信息 directory:department.parent_id:read 查看部门的父部门 ID directory:department.status:read 查看部门的停启用状态 directory:employee.base.external_id:read 查看员工自定义 ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
employee_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - employee_id: 企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。 获取employee_id的方式： - 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID - 通过 批量获取员工列表 的接口，通过手机号或邮箱查询员工ID。
默认值：open_id
当值为 employee_id，字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID
department_id_typestring否此次调用中使用的部门ID的类型
示例值：open_department_id
可选值有：
- open_department_id: 用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 相同。 - department_id: 用来标识租户内一个唯一的部门
默认值：open_department_id

请求体 ​

名称类型必填描述
filtermulti_filter_condition是查询条件了解更多：查询条件用法
  └ conditionsfilter_condition\[\]是比较表达式列表。多个表达式之间的关系默认为“and”
数据校验规则：
- 长度范围：0 ～ 10
    └ fieldstring是筛选条件的左值，值为字段的参数名称。
可选的筛选条件有： - parent_department_id
示例值："parent_department_id"
    └ operatorstring是比较操作符
可选值有： - eq：等于，支持任何类型的左值 - in：属于任一，不支持parent_department_id，右值为多个目标筛选值构成的数组（不得超过100个）
示例值："eq"
    └ valuestring是筛选条件的右值，内容为左值字段类型及操作符组合下，对应的值类型。其取值类型需与查询参数department_id_type的取值一致，最大长度为64字符，支持数字和字母。 使用parent_department_id条件时，根部门的ID可使用"0"
示例值：""0""
required_fieldsstring\[\]是需要查询的字段列表。将按照传递的字段列表返回有权限的行、列数据。不传则不会返回任何字段了解更多：字段枚举说明
示例值：["name"]
数据校验规则：
- 长度范围：0 ～ 100
page_requestpage_condition是分页信息
  └ page_sizeint否本次请求条数，最大100条
默认值：20 最小值：0
示例值：100
  └ page_tokenstring否顺序分页查询，不能跳页查询，支持深分页，在需要遍历全部数据的场景只能使用该方式。第一次传空字符串或者不传，后面传上一次的返回值中的page_token
示例值："iuu14140aknladna91ndas"

请求体示例 ​

json
{
    "filter": {
        "conditions": [
            {
                "field": "parent_department_id",
                "operator": "eq",
                "value": "\"0\""
            }
        ]
    },
    "required_fields": [
        "name"
    ],
    "page_request": {
        "page_size": 100,
        "page_token": "iuu14140aknladna91ndas"
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ departmentsdepartment\[\]部门信息
    └ department_idstring部门ID，与department_id_type类型保持一致
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.external_id:read 查看部门自定义 ID
    └ department_countdepartment_count部门成员计数与子部门计数。计算结果可能会有延迟
字段权限要求（满足任一）： directory:department.count:read 查看部门成员与子部门计数 directory:department.organization:read 查看部门组织架构信息
      └ recursive_members_countstring递归成员数量
      └ direct_members_countstring直属成员数量
      └ recursive_members_count_exclude_leadersstring递归成员数量(不含leader)
      └ recursive_departments_countstring递归子部门数量
      └ direct_departments_countstring直属子部门数量
    └ has_childboolean是否有子部门
字段权限要求（满足任一）： directory:department.has_child:read 查看部门是否有子部门 directory:department.organization:read 查看部门组织架构信息
    └ leadersdepartment_leader\[\]部门负责人
字段权限要求： directory:department.leader:read 查看部门负责人信息
      └ leader_typeint部门负责人类型
可选值有：
- 1: 主 - 2: 副
      └ leader_idstring部门负责人ID，与employee_id_type类型保持一致
    └ parent_department_idstring父部门ID，与department_id_type类型保持一致
字段权限要求（满足任一）： directory:department.organization:read 查看部门组织架构信息 directory:department.parent_id:read 查看部门的父部门 ID
    └ namei18n_text部门名称
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.name:read 查看部门的名称
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ enabled_statusboolean是否启用
字段权限要求： directory:department.status:read 查看部门的停启用状态
    └ order_weightstring部门排序权重
字段权限要求（满足任一）： directory:department.order_weight:read 查看部门排序权重 directory:department.organization:read 查看部门组织架构信息
    └ custom_field_valuescustom_field_value\[\]部门自定义字段值
字段权限要求： directory:department.custom_field:read 查看部门自定义字段信息
      └ field_typestring自定义字段类型
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 9: 电话 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表
      └ text_valuei18n_text文本字段值
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
      └ url_valueurl_value网页链接字段值
        └ link_texti18n_text网页标题
          └ default_valuestring默认值
          └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
        └ urlstring移动端网页链接
        └ pcurlstring桌面端网页链接
      └ enum_valueenum_value枚举字段值
        └ enum_idsstring\[\]选项结果ID
        └ enum_typestring选项类型
可选值有：
- 1: 文本 - 2: 图片
      └ user_valuesuser_value\[\]人员字段值
        └ idsstring\[\]人员ID，与employee_id_type类型保持一致
      └ phone_valuephone_value电话字段值
        └ phone_numberstring电话号
        └ extension_numberstring分机号
      └ field_keystring自定义字段key
    └ department_path_infosdepartment_base_info\[\]部门路径信息。排列顺序为根级到末级，不包含根部门
字段权限要求： directory:department.department_path:read 查看部门路径信息
      └ department_idstring部门ID，与department_id_type类型保持一致
      └ department_namei18n_texti18n文本
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ data_sourceint数据来源
可选值有：
- 1: 管理后台 - 2: 人事企业版 - 3: SCIM
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.data_source:read 查看部门数据来源
  └ page_responsepage_response分页结果
    └ has_moreboolean是否还有后续结果，如果has_more为true，代表还有数据没有完全返回，需要使用响应结果中的page_token，并再次请求才能取得剩下的数据。
    └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ abnormalsabnormal_record\[\]异常信息
    └ idstring异常ID
    └ row_errorint行级异常
可选值有：
- 0: 成功 - 1000: 没权限
    └ field_errorsmap<string, int>列级异常，key为字段名,value为下列枚举 可选值有：
- 1000: 无权限 - 2000: 服务异常 - 2003: 字段不存在

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "departments": [
            {
                "department_id": "h12921",
                "department_count": {
                    "recursive_members_count": "100",
                    "direct_members_count": "100",
                    "recursive_members_count_exclude_leaders": "100",
                    "recursive_departments_count": "100",
                    "direct_departments_count": "100"
                },
                "has_child": true,
                "leaders": [
                    {
                        "leader_type": 1,
                        "leader_id": "u273y71"
                    }
                ],
                "parent_department_id": "h12921",
                "name": {
                    "default_value": "张三",
                    "i18n_value": {
                        "zh_cn": "中文",
                        "ja_jp": "ja_jp_name",
                        "en_us": "en_us_name"
                    }
                },
                "enabled_status": true,
                "order_weight": "10",
                "custom_field_values": [
                    {
                        "field_type": "1",
                        "text_value": {
                            "default_value": "张三",
                            "i18n_value": {
                                "zh_cn": "中文",
                                "ja_jp": "ja_jp_name",
                                "en_us": "en_us_name"
                            }
                        },
                        "url_value": {
                            "link_text": {
                                "default_value": "张三",
                                "i18n_value": {
                                    "zh_cn": "中文",
                                    "ja_jp": "ja_jp_name",
                                    "en_us": "en_us_name"
                                }
                            },
                            "url": "https://m.bytedance.com/afnasjfna",
                            "pcurl": "http://www.fs.cn"
                        },
                        "enum_value": {
                            "enum_ids": [
                                "1"
                            ],
                            "enum_type": "1"
                        },
                        "user_values": [
                            {
                                "ids": [
                                    "1"
                                ]
                            }
                        ],
                        "phone_value": {
                            "phone_number": "18812345678",
                            "extension_number": "234234234"
                        },
                        "field_key": "C-1000001"
                    }
                ],
                "department_path_infos": [
                    {
                        "department_id": "1",
                        "department_name": {
                            "default_value": "张三",
                            "i18n_value": {
                                "zh_cn": "中文",
                                "ja_jp": "ja_jp_name",
                                "en_us": "en_us_name"
                            }
                        }
                    }
                ],
                "data_source": 1
            }
        ],
        "page_response": {
            "has_more": true,
            "page_token": "hiofbsabui214iokncaub"
        },
        "abnormals": [
            {
                "id": "eedasfwe",
                "row_error": 0,
                "field_errors": {
                    "name": 1000
                }
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4002221004invalid page token分页token无效，请检查page_token参数是否正确或已过期。
4002221005no page request无分页参数，请传入有效的page_request参数。
4002220009Filter field is invalid无效的filter，请检查filter参数的格式是否符合要求。
4002220010Exceeded the limit size分页大小超过限制，请将page_size参数调整至最大100以内。
4002220012The field is not support filter相关字段不支持过滤，请使用支持过滤的字段（如parent_department_id）。
4002220013The field does not support the operator字段不支持该操作符，请使用字段支持的操作符（如eq）。
4002220014Invalid field value非法字段右值，请检查value参数的值是否符合字段类型及操作符的要求。

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

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