服务端 API/通讯录/通讯录概述 # 通讯录概述 ## 业务介绍 在开放平台的设计中，通讯录可理解为企业的组织架构，包括企业部门信息，企业人员信息等，我们提供了一系列安全、可靠的 API，来方便你对通讯录信息进行操作。通过通讯录 API，你可以实现多种功能，例如： - 查看企业的组织架构 - 为企业创建新的用户 - 修改企业中已有用户的基本属性 - 维护用户和部门的关联关系 - 维护用户和用户组的关联关系 ### 接入流程   | 步骤 | 介绍 ---|---|--- 1 | 创建一个应用 | - 如需创建企业自建应用，可参考 [自建应用的开发流程](https://open.larksuite.com/document/home/introduction-to-custom-app-development/self-built-application-development-process)
- 如需创建应用商店应用，可参考 [开发和上架应用商店应用](https://open.larksuite.com/document/uMzNwEjLzcDMx4yM3ATM/uYzNwEjL2cDMx4iN3ATM) 2 | 调用API，对通讯录进行操作 | 调用API前，你需要先获取访问凭证并开启对应的权限，详情参见 [如何调用服务端API](https://open.larksuite.com/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)
你还可以在Postman工具中快速调试这些API：[![Run in Postman](https://run.pstmn.io/button.svg?lazyload=true&width=128&height=32)](https://god.gw.postman.com/run-collection/17195890-6fd42609-12b3-409b-8cbb-73656cf9d805?action=collection%2Ffork&collection-url=entityId%3D17195890-6fd42609-12b3-409b-8cbb-73656cf9d805%26entityType%3Dcollection%26workspaceId%3D55edcb9c-bbfe-45f5-a74a-efb882fe5384#?env%5Bfeishu-demo%5D=W3sia2V5IjoiYmFzZVVybCIsInZhbHVlIjoib3Blbi5mZWlzaHUuY24iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN0b3JlX2FwcF9pZCIsInZhbHVlIjoiY2xpX2EwYTUwODBjODRiODUwMTMiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN0b3JlX2FwcF9zZWNyZXQiLCJ2YWx1ZSI6InpFb0xLNHBjZE45VXBsNUpDOGNjcGZORlI3Q1FpbmNhIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhcHBfdGlja2V0IiwidmFsdWUiOiI3YTU1NjFlODdiMjkzYjFjOTEyZWM1NTQ2MDVjNDFlOWZhMjZkYzJmIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhcHBfYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJhLWNlOTJjZTNhMmRjNmM2ZjQzYTVjNzM2YmRlMzAxM2FkYzdlZGM2MzQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRlbmFudF9rZXkiLCJ2YWx1ZSI6IjczNjU4OGM5MjYwZjE3NWQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRlbmFudF9hY2Nlc3NfdG9rZW4iLCJ2YWx1ZSI6InQtMmQ0OWY4ZjMyOTY2YTEzYmMzN2ZiMWJkZWFmZTBkNDdhMjAwZDZkZiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiU1RBVEUiLCJ2YWx1ZSI6IjExIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJSRURJUkVDVF9VUkkiLCJ2YWx1ZSI6Imh0dHBzJTNBJTJGJTJGd3d3LmJhaWR1LmNvbSUyRiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidXNlcl9hY2Nlc3NfdG9rZW4iLCJ2YWx1ZSI6InUtMDJvYmhid01DSEl5c2ZhNzFWVGNUZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX2lkIiwidmFsdWUiOiJjbGlfYTA3ZmM0ZDVhMmY5NTAwYyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX3NlY3JldCIsInZhbHVlIjoiVlpBcFd0ZXc2UUdHQm1SbmxJNTF2aEZtbUU0bkJScmwiLCJlbmFibGVkIjp0cnVlfV0=)。使用方法参见[Postman模版使用说明](https://open.larksuite.com/document/tools-and-resources/postman-collection-data-manual) 3 | 监听事件，获知通讯录的变化 | 监听事件前，你需要先申请相应的权限，详情参见 [事件订阅概述](https://open.larksuite.com/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM) warning **为了隐私安全考虑，通讯录相关API设置了额外的权限控制要求：** - 应用通过API能够查询或修改的企业部门和人员范围 受到[企业管理员](https://www.larksuite.com/hc/zh-CN/articles/360049067822)配置的通讯录范围限制，你的应用仅能操作已获得授权的通讯录范围，详情请参见[通讯录权限范围说明](https://open.larksuite.com/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)； - 商店应用无法修改用户所在企业的通讯录信息。 ## 资源介绍 通讯录业务域以“资源”为中心进行开放，资源的关系图如下： ![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/cef36972572508d94a05ddff52ac5a2f_HBL9GJfb7A.png?lazyload=true&width=1640&height=1284) 资源的定义如下： 资源 | 资源定义 ---|--- [用户](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/field-overview) | Lark某个企业里的一个用户。 [部门](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) | 对应Lark某个企业里的组织架构树上的一个节点。 [用户组](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/overview) | 部门之外的另一种成员圈定方式，用户组可关联用户。分为[静态用户组](https://www.larksuite.com/hc/zh-CN/articles/360049067479)和[动态用户组](https://www.larksuite.com/hc/zh-CN/articles/360049067874) [人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/overview) | 一种特殊的用户属性字段，用于标记用户的身份类型。默认值为：正式、实习、外包、劳务、顾问。企业可基于自身管理诉求自定义该字段的枚举值，每个用户只能引用一个枚举值。 [自定义用户字段](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/custom_attr/overview) | 由企业自定义的用户字段，用于不同企业基于自身管理诉求灵活表征用户信息，自定义字段由[企业管理员](https://www.larksuite.com/hc/zh-CN/articles/360049067822)在[企业管理后台 - 组织架构 - 成员字段管理](http://www.larksuite.com/admin/contacts/employee-field-new/custom) 里进行创建、更新操作，可以通过接口可获取企业的所有自定义字段。
![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/916ed86bcfe8cf6413a201bd6426f273_Cp6kDjtCKO.png?lazyload=true&width=1640&height=774)
![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/a780f8cf26717b120edc647bab48cdb9_hDqwt3VBsd.png?lazyload=true&width=1640&height=937) [通讯录权限范围](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/scope/overview) | 应用通过通讯录接口可以操作的组织架构数据范围，由[企业管理员](https://www.larksuite.com/hc/zh-CN/articles/360049067822)在 [企业管理后台 - 工作台 - 应用管理](http://www.larksuite.com/admin/appCenter/manage) 给不同应用设置。
![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/8ba4dbecb02390a47a3e418932fd1aa5_4oMArG3vdq.png?lazyload=true&width=1640&height=1074)
![6e868e1d-299f-43ce-9078-ba273827b10c (1).png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/f63dd6f78e6b2488e02a8ce78680aafe_m5zuNEK1Ol.png?lazyload=true&width=1277&height=436) 以下将详细介绍每个资源的字段、方法、事件。 ### 资源：用户 User 查看[资源字段及示例](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/field-overview) #### 方法列表 > “商店”代表 [应用商店应用](https://open.larksuite.com/document/home/app-types-introduction/overview)；“自建”代表 [企业自建应用](https://open.larksuite.com/document/home/app-types-introduction/overview) **[方法 (API)](https://open.larksuite.com/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [创建用户](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/create)
`POST` /open-apis/contact/v3/users
> 向通讯录创建一个用户，可以理解为员工入职 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [获取单个用户信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/get)
`GET` /open-apis/contact/v3/users/:user_id
> 获取通讯录中单个用户的信息 | 以应用身份读取通讯录 | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取部门直属用户列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/find_by_department)
`GET` /open-apis/contact/v3/users/find_by_department
> 获取部门下直属用户列表 | 以应用身份读取通讯录
获取部门组织架构信息 | `tenant_access_token`
`user_access_token` | **✓** | **✓** [修改用户部分信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/patch)
`PATCH` /open-apis/contact/v3/users/:user_id
>更新通讯录中用户的字段，未传递的参数不会更新 | 更新通讯录
更新用户基本信息 | `tenant_access_token`
`user_access_token` | **X** | **✓** [更新用户所有信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/update)
`PUT` /open-apis/contact/v3/users/:user_id
>更新通讯录中用户的字段 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [删除用户](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/delete)
`DELETE` /open-apis/contact/v3/users/:user_id
>向通讯录删除一个用户信息，可以理解为员工离职 | 更新通讯录 | `tenant_access_token` | **X** | **✓** #### 事件列表 **[事件 (Event)](https://open.larksuite.com/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建 ---|---|---|---|---|--- [员工信息被修改](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/events/updated) | 员工信息被修改时 | 以应用身份读取通讯录 | contact.user.updated_v3 | **✓** | **✓** [员工入职](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/events/created) | 员工入职时 | 以应用身份读取通讯录 | contact.user.created_v3 | **✓** | **✓** [员工离职](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/events/deleted) | 员工离职时 | 以应用身份读取通讯录 | contact.user.deleted_v3 | **✓** | **✓** ### 资源：部门 Department 查看[资源字段及示例](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) #### 方法列表 **[方法 (API)](https://open.larksuite.com/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [创建部门](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/create)
`POST` /open-apis/contact/v3/departments
>向通讯录中创建部门 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [获取单个部门信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/get)
`GET` /open-apis/contact/v3/departments/:department_id
>向通讯录获取单个部门信息 | 以应用身份读取通讯录 | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取子部门列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/children)
`GET` open-apis/contact/v3/departments/:department_id/children
>获取当前部门子部门列表 | 以应用身份读取通讯录
获取部门组织架构信息 | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取父部门信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/parent)
`GET` /open-apis/contact/v3/departments/parent
>递归获取部门父部门的信息 | 以应用身份读取通讯录
获取部门组织架构信息 | `tenant_access_token`
`user_access_token` | **✓** | **✓** [搜索部门](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/search)
`POST` /open-apis/contact/v3/departments/search
>通过关键词查询可见的部门数据 | 以应用身份读取通讯录 | `user_access_token` | **✓** | **✓** [修改部门部分信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/patch)
`PATCH` /open-apis/contact/v3/departments/:department_id
>更新通讯录中部门的信息中的任一个字段 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [更新部门所有信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/update)
`PUT` /open-apis/contact/v3/departments/:department_id
>用于更新当前部门所有信息 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [删除部门](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/delete)
`DELETE` /open-apis/contact/v3/departments/:department_id
>向通讯录中删除部门 | 更新通讯录 | `tenant_access_token` | **X** | **✓** #### 事件列表 **[事件 (Event)](https://open.larksuite.com/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建 ---|---|---|---|---|--- [部门信息被修改](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/events/updated) | 部门信息被修改时 | 以应用身份读取通讯录 | contact.department.updated_v3 | **✓** | **✓** [部门被创建](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/events/created) | 部门被创建时 | 以应用身份读取通讯录 | contact.department.created_v3 | **✓** | **✓** [部门被删除](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/events/deleted) | 部门被删除时 | 以应用身份读取通讯录 | contact.department.deleted_v3 | **✓** | **✓** ### 资源：用户组 User Group 查看[资源字段及示例](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/overview) #### 方法列表 **[方法 (API)](https://open.larksuite.com/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [创建用户组](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/create)
`POST` /open-apis/contact/v3/group
>新增用户组 | 更新用户组信息 | `tenant_access_token` | **X** | **✓** [更新用户组](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/patch)
`PATCH` /open-apis/contact/v3/group/:group_id
>更新某个用户组信息 | 更新用户组信息 | `tenant_access_token` | **X** | **✓** [删除用户组](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/delete)
`DELETE` /open-apis/contact/v3/group/:group_id
>删除某个用户组 | 更新用户组信息 | `tenant_access_token` | **X** | **✓** [查询用户组](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/get)
`GET` /open-apis/contact/v3/group/:group_id
>获取某个用户组信息 | 获取用户组信息 | `tenant_access_token` | **✓** | **✓** [查询用户组列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/simplelist)
`GET` /open-apis/contact/v3/group/simplelist
>查询组织的用户组列表 | 获取用户组信息 | `tenant_access_token` | **✓** | **✓** [添加用户组成员](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group-member/add)
`POST` /open-apis/contact/v3/group/:group_id/member/add
>向某个用户组中添加成员 | 更新用户组信息 | `tenant_access_token` | **X** | **✓** [移除用户组成员](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group-member/remove)
`PUT` /open-apis/contact/v3/group/:group_id/member/remove
>用于移除用户组中的成员 | 更新用户组信息 | `tenant_access_token` | **X** | **✓** [查询用户组成员列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group-member/simplelist)
`GET` /open-apis/contact/v3/group/:group_id/member/simplelist
>获取用户组中的成员列表 | 获取用户组信息 | `tenant_access_token` | **✓** | **✓** ### 资源：人员类型 Employee Type 查看[资源字段及示例](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/overview) #### 方法列表 **[方法 (API)](https://open.larksuite.com/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [查询人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/list)
`GET` /open-apis/contact/v3/employee_type_enums
>获取员工的人员类型 | 以应用身份读取通讯录 | `tenant_access_token` | **✓** | **✓** [更新人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/update)
`PUT` /open-apis/contact/v3/employee_type_enums/:enum_id
>更新自定义人员类型 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [删除人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/delete)
`DELETE` /open-apis/contact/v3/employee_type_enums/:enum_id
>删除自定义人员枚举 | 更新通讯录 | `tenant_access_token` | **X** | **✓** [新增人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/create)
`POST` /open-apis/contact/v3/employee_type_enums
>新增自定义人员类型 | 更新通讯录 | `tenant_access_token` | **X** | **✓** #### 事件列表 **[事件 (Event)](https://open.larksuite.com/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建 ---|---|---|---|---|--- [新建人员类型事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/events/created) | 人员类型被创建时 | 以应用身份读取通讯录 | contact.employee_type_enum.created_v3 | **✓** | **✓** [启用人员类型事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/events/actived) | 人员类型被启用时 | 以应用身份读取通讯录 | contact.employee_type_enum.actived_v3 | **✓** | **✓** [停用人员类型事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/events/deactivated) | 人员类型被停用时 | 以应用身份读取通讯录 | contact.employee_type_enum.deactivated_v3 | **✓** | **✓** [修改人员类型名称事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/events/updated) | 人员类型被修改时 | 以应用身份读取通讯录 | contact.employee_type_enum.updated_v3 | **✓** | **✓** [删除人员类型事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/events/deleted) | 人员类型被删除时 | 以应用身份读取通讯录 | contact.employee_type_enum.deleted_v3 | **✓** | **✓** ### 资源：自定义用户字段 Custom user fields 查看[资源字段及示例](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/custom_attr/overview) #### 方法列表 **[方法 (API)](https://open.larksuite.com/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)**（选择其一） | 商店 | 自建 ---|---|---|---|--- [获取企业自定义用户字段](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/custom_attr/list)
`GET` /open-apis/contact/v3/custom_attrs
>获取企业自定义的用户字段配置信息 | 以应用身份读取通讯录 | `tenant_access_token` | **✓** | **✓** ### 资源：通讯录权限范围 Contact Scope 查看[资源字段及示例](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/scope/overview) #### 事件列表 **[事件 (Event)](https://open.larksuite.com/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建 ---|---|---|---|---|--- [通讯录范围权限被变更](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/scope/events/updated) | 通讯录范围权限发生变更时 | 以应用身份读取通讯录 | contact.scope.updated_v3 | **✓** | **✓**