概述 - 飞书 API

应用场景

通讯录可理解为企业的组织架构，包括企业部门信息、企业人员信息等，我们提供了一系列安全、可靠的 API，来方便用户对通讯录信息进行操作。例如：

查看企业的组织架构

为企业创建新的用户

修改企业中已有用户的基本属性

维护用户和部门的关联关系

维护用户和用户组的关联关系

更多应用场景可参考客户案例HR 系统集成飞书，“入转调离”管理更轻松。

接入流程

步骤	介绍
创建一个应用	如需创建企业自建应用，可参考自建应用的开发流程如需创建应用商店应用，可参考开发和上架应用商店应用
调用API，对通讯录进行操作	调用 API 前，你需要先获取访问凭证并开启对应的权限，详情参见如何调用服务端API你还可以在 API 调试台中快速调试这些 API ，使用方法参见API 调试台使用指南
监听事件，获知通讯录的变化	监听事件前，你需要先申请相应的权限，详情参见事件订阅概述

开发教程

教程名称	教程步骤拆解
将企业组织架构同步到飞书	创建一个飞书应用确定要调用的API 开启应用权限获取应用访问凭证创建和更新部门创建和更新用户信息查看已同步到飞书的组织架构

资源介绍

资源关系

通讯录业务域以资源为中心进行开放，资源的关系图如下：

以下将详细介绍每个资源的字段、方法、事件。

用户

资源定义

用户是指飞书某个企业里的一个用户。有关用户的介绍，请参考用户概述。

方法列表

方法	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
创建用户	更新通讯录	tenant_access_token	X	✓
删除用户	更新通讯录	tenant_access_token	X	✓
修改用户部分信息	更新通讯录更新用户基本信息	tenant_access_tokenuser_access_token	X	✓
更新用户所有信息	更新通讯录	tenant_access_token	X	✓
获取单个用户信息	以应用身份读取通讯录	tenant_access_tokenuser_access_token	✓	✓
获取部门直属用户列表	以应用身份读取通讯录获取部门组织架构信息	tenant_access_tokenuser_access_token	✓	✓
通过手机号或邮箱获取用户ID	通过手机号或邮箱获取用户 ID	tenant_access_token	✓	✓

事件列表

事件	权限要求（满足任一）	事件类型	应用商店应用	企业自建应用
员工入职	以应用身份读取通讯录	contact.user.created_v3	✓	✓
员工离职	以应用身份读取通讯录	contact.user.deleted_v3	✓	✓
员工信息被修改	以应用身份读取通讯录	contact.user.updated_v3	✓	✓

部门

资源定义

部门对应飞书某个企业里的组织架构树上的一个节点。有关部门的介绍，请参考部门概述。

方法列表

方法	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
创建部门	更新通讯录	tenant_access_token	X	✓
删除部门	更新通讯录	tenant_access_token	X	✓
修改部门部分信息	更新通讯录	tenant_access_token	X	✓
更新部门所有信息	更新通讯录	tenant_access_token	X	✓
部门群转为普通群	更新通讯录	tenant_access_token	X	✓
获取单个部门信息	以应用身份读取通讯录	tenant_access_tokenuser_access_token	✓	✓
获取子部门列表	以应用身份读取通讯录获取部门组织架构信息	tenant_access_tokenuser_access_token	✓	✓
获取父部门信息	以应用身份读取通讯录获取部门组织架构信息	tenant_access_tokenuser_access_token	✓	✓
搜索部门	以应用身份读取通讯录	user_access_token	✓	✓

事件列表

事件	权限要求（满足任一）	事件类型	应用商店应用	企业自建应用
部门信息被修改	以应用身份读取通讯录	contact.department.updated_v3	✓	✓
部门被创建	以应用身份读取通讯录	contact.department.created_v3	✓	✓
部门被删除	以应用身份读取通讯录	contact.department.deleted_v3	✓	✓

用户组

资源定义

用户组表示部门之外的另一种成员圈定方式，用户组可关联用户，分为静态用户组和动态用户组。有关用户组的介绍，请参考用户组概述。

方法列表

方法	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
创建用户组	更新用户组信息	tenant_access_token	X	✓
更新用户组	更新用户组信息	tenant_access_token	X	✓
删除用户组	更新用户组信息	tenant_access_token	X	✓
查询用户组	获取用户组信息	tenant_access_token	✓	✓
查询用户组列表	获取用户组信息	tenant_access_token	✓	✓
查询用户所属用户组	获取用户组信息	tenant_access_token	✓	✓
查询用户组成员列表	获取用户组信息	tenant_access_token	✓	✓
添加用户组成员	更新用户组信息	tenant_access_token	X	✓
批量添加用户组成员	更新用户组信息	tenant_access_token	X	✓
移除用户组成员	更新用户组信息	tenant_access_token	X	✓
批量移除用户组成员	更新用户组信息	tenant_access_token	X	✓

单位

资源定义

单位是单个租户内部用于表征大型集团企业中的“子公司”、“分支机构”的组织实体，一个“单位”可以被理解为现实世界中一个集团企业的‘子公司’，单位目前的主要作用是在部分用户权限上实现“子公司”级别的权限隔离。更多详情请参考单位资源概述。

方法列表

方法	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
创建单位	更新单位信息	tenant_access_token	X	✓
修改单位信息	更新单位信息	tenant_access_token	X	✓
删除单位	更新单位信息	tenant_access_token	X	✓
获取单位信息	获取单位信息	tenant_access_token	X	✓
批量获取单位列表	获取单位信息	tenant_access_token	X	✓
建立部门与单位的绑定关系	更新单位信息	tenant_access_token	X	✓
解除部门与单位的绑定关系	更新单位信息	tenant_access_token	X	✓
获取单位绑定的部门列表	获取单位信息	tenant_access_token	X	✓

人员类型

资源定义

人员类型是一种特殊的用户属性字段，用于标记用户的身份类型，例如正式、实习、外包、劳务、顾问。企业可基于自身管理诉求自定义该字段的枚举值，每个用户只能引用一个枚举值。有关人员类型的介绍，请参考人员类型概述。

方法列表

方法	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
查询人员类型	以应用身份读取通讯录	tenant_access_token	✓	✓
更新人员类型	更新通讯录	tenant_access_token	X	✓
删除人员类型	更新通讯录	tenant_access_token	X	✓
新增人员类型	更新通讯录	tenant_access_token	X	✓

事件列表

事件	权限要求（满足任一）	事件类型	应用商店应用	企业自建应用
新建人员类型事件	以应用身份读取通讯录	contact.employee_type_enum.created_v3	✓	✓
启用人员类型事件	以应用身份读取通讯录	contact.employee_type_enum.actived_v3	✓	✓
停用人员类型事件	以应用身份读取通讯录	contact.employee_type_enum.deactivated_v3	✓	✓
修改人员类型名称事件	以应用身份读取通讯录	contact.employee_type_enum.updated_v3	✓	✓
删除人员类型事件	以应用身份读取通讯录	contact.employee_type_enum.deleted_v3	✓	✓

自定义用户字段

资源定义

自定义用户字段是企业自定义的用户字段，用于不同企业基于自身管理诉求灵活表征用户信息，自定义字段由企业管理员在企业管理后台 > 组织架构 > 成员字段管理里进行创建、更新操作，可以通过接口获取企业的所有自定义字段。有关自定义用户字段的介绍，请参考自定义字段概述。

方法列表

方法	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
获取企业自定义用户字段	以应用身份读取通讯录	tenant_access_token	✓	✓

事件列表

事件	权限要求（满足任一）	事件类型	应用商店应用	企业自建应用
成员字段变更	以应用身份读取通讯录	contact.custom_attr_event.updated_v3	✓	✓

通讯录权限范围

资源定义

通讯录权限范围表示应用通过通讯录接口可以操作的组织架构数据范围，由企业管理员在企业管理后台 > 工作台 > 应用管理中设置。有关通讯录权限范围的介绍，请参考通讯录权限范围概述。

方法列表

事件	权限要求（满足任一）	访问凭证（选择其一）	应用商店应用	企业自建应用
获取通讯录授权范围	以应用身份读取通讯录	tenant_access_token	✓	✓

事件列表

事件	权限要求（满足任一）	事件类型	应用商店应用	企业自建应用
通讯录范围权限被变更	以应用身份读取通讯录	contact.scope.updated_v3	✓	✓

概述

应用场景#

接入流程#

开发教程#

资源介绍#

资源关系#

用户#

资源定义#

方法列表#

事件列表#

部门#

资源定义#

方法列表#

事件列表#

用户组#

资源定义#

方法列表#

单位#

资源定义#

方法列表#

人员类型#

资源定义#

方法列表#

事件列表#

自定义用户字段#

资源定义#

方法列表#

事件列表#

通讯录权限范围#

资源定义#

方法列表#

事件列表#

应用场景

接入流程

开发教程

资源介绍

资源关系

用户

资源定义

方法列表

事件列表

部门

资源定义

方法列表

事件列表

用户组

资源定义

方法列表

单位

资源定义

方法列表

人员类型

资源定义

方法列表

事件列表

自定义用户字段

资源定义

方法列表

事件列表

通讯录权限范围

资源定义

方法列表

事件列表