> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 概述

> 面向企业管理者、IT 负责人和开发者，介绍钉钉通讯录的能力边界与查看方式，并给出开放概览、使用教程和核心名词解释，为系统集成奠定基础。

本文档旨在帮助读者全面了解钉钉通讯录，通过阅读本文档，企业管理者、IT 负责人和开发者可以快速掌握通讯录的能力边界，为后续的系统集成和业务创新奠定基础。

## 什么是钉钉通讯录

钉钉通讯录是企业内部信息统一管理的核心基础设施，它以数字化方式呈现企业的组织架构和人员信息，为企业成员提供快速找人、高效协作的基础能力。

更多功能介绍请参考[钉钉使用手册-企业通讯录](https://docs.dingtalk.io/i/p/Y7kmbokZp3pgGLq2/docs/Y7kmbpxy30LLzLq2?dontjump=true#)。

| **维度** | **说明**                          |
| ------ | ------------------------------- |
| 本质     | 企业组织结构的数字化表达载体                  |
| 形态     | 树形部门结构 + 人员信息数据库                |
| 作用     | 连接企业人、事、物的枢纽，支撑审批流、消息路由、权限控制等场景 |

## 如何查看通讯录

### 企业管理员视角

企业管理员可通过以下方式管理和查看通讯录：

* 钉钉管理后台：登录登录[钉钉管理后台](https://oa.dingtalk.io/)，进入**内部通讯录**模块，可进行通讯录的完整管理和配置
* 通讯录设置：配置通讯录的可见性规则、自定义字段、高管模式等高级功能

![iShot2022-01-10 17](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/3305512461/p381941.png)

### 普通成员

普通组织成员可通过以下终端查看通讯录：

* **PC 端钉钉**：在钉钉 PC 客户端中点击「通讯录」标签，可查看企业组织架构和联系详情
* **手机端钉钉**：在钉钉移动 App 中进入「通讯录」页面，支持按部门浏览和关键词搜索
* **Web 端钉钉**：通过钉钉网页版访问通讯录功能

## 开放概览

### 开放接口列表

通讯录提供了丰富的接口开放能力，开发者通过API接口可以实现通讯录和企业业务系统打通。

#### 用户通讯录

| API         | 说明               | API 版本 |
| ----------- | ---------------- | ------ |
| 获取用户通讯录个人信息 | 获取企业用户通讯录中的个人信息。 | 新版     |

#### 通讯录权限

| API       | 说明         | API 版本 |
| --------- | ---------- | ------ |
| 获取通讯录权限范围 | 获取通讯录权限范围。 | 旧版     |

#### 用户管理

| API                                                                                                     | API说明                 | API 版本 |
| ------------------------------------------------------------------------------------------------------- | --------------------- | ------ |
| [创建用户](/zh/open/development/user-information-creation)                                                  | 创建新用户。                | 旧版     |
| [更新用户信息](/zh/open/development/user-information-update)                                                  | 更新指定的用户信息。            | 旧版     |
| [删除用户](/zh/open/development/delete-a-user)                                                              | 根据用户的userid删除指定用户。    | 旧版     |
| [查询用户详情](/zh/open/development/query-user-details)                                                       | 获取指定用户的详细信息。          | 旧版     |
| [获取部门用户基础信息](/zh/open/development/queries-the-simple-information-of-a-department-user)                  | 获取指定部门的用户基础信息。        | 旧版     |
| [获取部门用户userid列表](/zh/open/development/query-the-list-of-department-userids)                             | 获取指定部门的userid列表。      | 旧版     |
| [获取部门用户详情](/zh/open/development/queries-the-complete-information-of-a-department-user)                  | 获取指定部门中的用户详细信息。       | 旧版     |
| [获取员工人数](/zh/open/development/user-management-acquires-number-employees)                                | 获取员工人数。               | 旧版     |
| [获取未登录钉钉的员工列表](/zh/open/development/queries-the-inactive-users-or-active-users-under-an-enterprise)     | 查询指定日期内未登录钉钉的企业员工列表。  | 旧版     |
| [根据手机号查询用户](/zh/open/development/query-users-by-phone-number)                                           | 根据手机号获取用户的userId。     | 旧版     |
| [根据unionid获取用户userid](/zh/open/development/query-a-user-by-the-union-id)                                | 根据unionid获取用户的userid。 | 旧版     |
| [获取管理员列表](/zh/open/development/query-the-administrator-list)                                            | 查询管理员列表。              | 旧版     |
| [获取管理员通讯录权限范围](/zh/open/development/query-permissions-of-the-administrator-address-book)                | 获取管理员通讯录权限范围。         | 旧版     |
| [获取管理员的应用管理权限](/zh/open/development/obtains-the-administrator-s-microapplication-management-permission) | 获取管理员的应用管理权限。         | 旧版     |
| [查询离职记录列表](/zh/open/development/query-the-details-of-employees-who-have-left-office)                    | 查询企业离职记录列表。           | 新版     |
| [设置高管模式](/zh/open/development/update-executive-settings)                                                | 设置员工的高管模式。            | 新版     |
| [获取用户高管模式设置](/zh/open/development/get-user-executive-mode-settings)                                     | 获取用户高管模式的设置详情。        | 新版     |
| [删除用户属性可见性设置](/zh/open/development/delete-enterprise-employee-attribute-field-visibility-settings)      | 删除企业员工属性字段可见性设置。      | 新版     |
| [获取用户属性可见性设置](/zh/open/development/pull-hidden-property-field-for-enterprise-employees)                 | 获取企业员工属性字段隐藏设置。       | 新版     |
| [设置用户属性可见性](/zh/open/development/add-or-update-the-hidden-settings-of-the-employee-property)            | 新增或更新企业员工属性字段隐藏设置。    | 新版     |
| [搜索用户userId](/zh/open/development/address-book-search-user-id)                                          | 根据用户名称搜索用户userId。     | 新版     |
| [通讯录userId排序](/zh/open/development/address-book-userid-sorting)                                         | 根据用户姓名拼音进行userId排序。   | 新版     |

#### 部门管理

| API                                                                                             | 说明                 | API 版本 |
| ----------------------------------------------------------------------------------------------- | ------------------ | ------ |
| [创建部门](/zh/open/development/address-book-creation-department-established-department)            | 创建新部门。             | 旧版     |
| [更新部门](/zh/open/development/address-book-update-department)                                     | 更新部门信息。            | 旧版     |
| [删除部门](/zh/open/development/address-book-deletion-department)                                   | 根据部门ID删除指定部门。      | 旧版     |
| [搜索部门ID](/zh/open/development/address-book-search-department-id)                                | 搜索部门ID。            | 新版     |
| [获取部门详情](/zh/open/development/query-department-details0-v2)                                     | 根据部门ID获取指定部门详情。    | 旧版     |
| [获取部门列表](/zh/open/development/user-management-acquires-the-list-departments)                    | 获取下一级部门基础信息。       | 旧版     |
| [获取子部门ID列表](/zh/open/development/obtain-the-list-of-sub-department-ids)                         | 获取企业部门下的所有直属子部门列表。 | 旧版     |
| [获取指定部门的所有父部门列表](/zh/open/development/query-the-list-of-all-parent-departments-of-a-department) | 获取指定部门的所有父部门ID列表。  | 旧版     |
| [获取指定用户的所有父部门列表](/zh/open/development/queries-the-list-of-all-parent-departments-of-a-user)     | 查询指定用户所属的所有父级部门。   | 旧版     |

#### 角色管理

| API         | 说明              | API 版本 |
| ----------- | --------------- | ------ |
| 创建角色        | 创建新角色。          | 旧版     |
| 创建角色组       | 创建角色组。          | 旧版     |
| 更新角色名称      | 更新角色名称。         | 旧版     |
| 批量增加员工角色    | 批量增加员工角色。       | 旧版     |
| 删除角色        | 根据角色ID删除指定的角色。  | 旧版     |
| 批量删除员工角色    | 批量删除员工的角色。      | 旧版     |
| 设定角色成员管理范围  | 设定角色成员管理范围。     | 旧版     |
| 获取角色组列表     | 获取角色组信息。        | 旧版     |
| 获取角色列表      | 获取角色列表。         | 旧版     |
| 获取角色详情      | 根据角色ID获取指定角色详情。 | 旧版     |
| 获取指定角色的员工列表 | 获取指定角色的员工列表。    | 旧版     |

#### 外部联系人

| API         | 说明              | API 版本 |
| ----------- | --------------- | ------ |
| 添加外部联系人     | 添加企业外部联系人。      | 旧版     |
| 删除外部联系人     | 删除企业外部联系人。      | 旧版     |
| 更新外部联系人     | 更新企业外部联系人。      | 旧版     |
| 获取外部联系人列表   | 获取企业外部联系人列表。    | 旧版     |
| 获取外部联系人标签列表 | 获取企业外部联系人的标签。   | 旧版     |
| 获取外部联系人详情   | 获取企业外部联系人的详细信息。 | 旧版     |

#### 企业账号

| API                                                                                               | 说明                             | API 版本 |
| ------------------------------------------------------------------------------------------------- | ------------------------------ | ------ |
| [创建SSO企业账号](/zh/open/development/create-an-sso-account)                                           | 创建SSO企业账号新用户。                  | 旧版     |
| [企业账号修改钉钉号](/zh/open/development/api-changedingtalkid)                                            | 修改企业账号钉钉号。                     | 新版     |
| [创建钉钉自建企业账号](/zh/open/development/create-dingtalk-user-created-dedicated-account)                 | 创建钉钉自建企业账号新用户。                 | 旧版     |
| [更新企业账号用户信息](/zh/open/development/update-dedicated-accounts-information)                          | 更新指定的企业账号用户信息。                 | 旧版     |
| [查询企业账号用户详情](/zh/open/development/queries-the-details-of-a-dedicated-account)                     | 获取指定企业账号用户的详细信息。               | 旧版     |
| [启用企业账号](/zh/open/development/enable-a-dedicated-account)                                         | 启用指定企业账号。                      | 新版     |
| [停用企业账号](/zh/open/development/disable-an-exclusive-account)                                       | 停用指定的企业账号。                     | 新版     |
| [强制登出企业账号](/zh/open/development/force-logout-from-dedicated-account)                              | 强制登出指定的企业账号。                   | 新版     |
| [查询企业账号状态](/zh/open/development/query-dedicated-account-status-1)                                 | 查询某企业账号的启用状态。                  | 新版     |
| [查询企业账号拥有的组织](/zh/open/development/you-can-call-this-operation-to-query-the-organization-that)    | 查询企业账号在哪些企业下拥有创建者身份，并获取这些企业信息。 | 新版     |
| [授权企业账号可加入多组织](/zh/open/development/authorize-a-dedicated-account-to-join-multiple-organizations) | 授权企业账号可以加入多个组织。                | 新版     |
| [邀请其他组织企业账号加入](/zh/open/development/invite-other-organization-specific-accounts-to-join)          | 加入其他组织企业账号进入本组织。               | 旧版     |
| [获取部门企业账号用户详情](/zh/open/development/queries-account-details)                                      | 获取指定部门中的用户详细信息。                | 旧版     |
| [根据手机号查询企业账号用户](/zh/open/development/obtain-the-userid-of-your-mobile-phone-number)               | 根据手机号获取企业账号用户的userId。          | 旧版     |
| [企业账号转交主管理员（创建者）](/zh/open/development/transfer-exclusive-account-to-main-administrator-creator)  | 将本组织内某企业账号有所有权的组织，转交给另一企业账号。   | 新版     |
| 根据迁移后的dingId查询原dingId                                                                             | 根据迁移后的dingId查询原dingId。         | 新版     |
| 根据迁移后的unionId查询原unionId                                                                           | 根据迁移后的unionId查询原unionId。       | 新版     |
| 根据原dingId查询迁移后的dingId                                                                             | 根据原dingId查询迁移后的dingId。         | 新版     |
| 根据原unionId查询迁移后的unionId                                                                           | 根据原unionId查询迁移后的unionId。       | 新版     |
| [授权其他组织查看本组织的企业账号信息](/zh/open/development/api-orgaccountmobilevisibleinotherorg)                  | 其他组织查看本组织的企业账号信息的具体字段。         | 新版     |

#### 企业管理

| API                                                                                                           | 说明                 | API 版本 |
| ------------------------------------------------------------------------------------------------------------- | ------------------ | ------ |
| 获取企业认证信息                                                                                                      | 获取企业认证信息。          | 新版     |
| 获取企业邀请信息                                                                                                      | 获取企业的邀请信息。         | 新版     |
| 获取企业最新钉钉指数信息                                                                                                  | 获取企业最新钉钉指数信息。      | 新版     |
| [查询管理员是否有应用管理权限](/zh/open/development/check-whether-the-administrator-has-application-management-permissions) | 查询企业管理员是否有应用的管理权限。 | 新版     |

| API       | 说明                 | API 版本 |
| --------- | ------------------ | ------ |
| 获取部门详情    | 根据部门ID获取部门详情。      | 旧版     |
| 获取部门下人员列表 | 获取部门下的人员列表信息。      | 旧版     |
| 获取部门列表    | 根据部门ID获取行业通讯录部门列表。 | 旧版     |
| 获取部门用户详情  | 获取部门用户详情。          | 旧版     |
| 获取企业信息    | 获取行业通讯录的企业信息。      | 旧版     |

#### 通讯录ID转译

| API                                                                                        | 说明                                      | API 版本 |
| ------------------------------------------------------------------------------------------ | --------------------------------------- | ------ |
| [异步转译通讯录ID](/zh/open/development/asynchronous-address-book-file-content-translation)       | 起异步通讯录ID内容转译，替换产品方案商通讯录权限范围内的用户ID和部门ID。 | 新版     |
| [获取异步转译任务结果](/zh/open/development/obtains-the-results-of-an-asynchronous-translation-task) | 获取查询已经提交过的转译任务结果。                       | 新版     |

#### 通讯录可见性管理

| API            | 说明              | API 版本 |
| -------------- | --------------- | ------ |
| 获取通讯录隐藏设置      | 批量获取通讯录隐藏的设置列表。 | 新版     |
| 删除通讯录隐藏设置      | 删除通讯录隐藏设置。      | 新版     |
| 新增或更新通讯录隐藏设置   | 新增或更新通讯录隐藏设置。   | 新版     |
| 设置部门可见性优先级     | 设置通讯录部门可见性优先级。  | 新版     |
| 新增或修改限制查看通讯录设置 | 新增或修改限制查看通讯录设置。 | 新版     |
| 获取限制查看通讯录设置列表  | 获取限制查看通讯录的设置列表。 | 新版     |
| 删除限制查看通讯录设置    | 删除限制查看通讯录设置     | 新版     |

| API                       | 说明                                 | API 版本 |
| ------------------------- | ---------------------------------- | ------ |
| 创建上下游组织                   | 创建上下游组织。                           | 新版     |
| 解除关联组织                    | 解除关联组织关系。                          | 新版     |
| 获取上下游组织的邀请信息              | 获取上下游组织的邀请链接。                      | 新版     |
| 批量通过伙伴组织的加入申请             | 批量通过伙伴组织加入上下游组织申请。                 | 新版     |
| 更新伙伴组织在上下游组织内的属性信息        | 更新伙伴组织在上下游组织内内的属性信息。               | 新版     |
| 设置伙伴组织在上下游组织内的可见范围        | 设置伙伴组织在上下游组织内的可见范围。                | 新版     |
| 获取企业已经加入的或申请加入中的上下游组织的信息  | 获取企业已经加入的上下游组织信息或获取企业已经加入的上下游组织信息。 | 新版     |
| 获取已加入或正在申请加入上下游组织的组织和个人信息 | 通过上下游组织组织ID获取加入或申请加入上下游组织的组织和个人信息。 | 新版     |

| API               | 说明                 | API 版本 |
| ----------------- | ------------------ | ------ |
| 解除关联组织            | 解除关联组织关系。          | 新版     |
| 获取主干组织列表          | 获取主干组织列表。          | 新版     |
| 获取分支组织列表          | 获取分支组织列表。          | 新版     |
| 批量通过伙伴组织的加入申请     | 批量通过分支组织加入主干组织申请。  | 新版     |
| 获取上下级组织分支授权的数据    | 获取上下级组织分支授权的数据。    | 新版     |
| 设置分支组织在主干组织内的可见范围 | 设置分支组织在主干组织内的可见范围。 | 新版     |
| 更新分支组织在主干组织内的属性信息 | 更新分支组织在主干组织内的属性信息。 | 新版     |

### 回调事件列表

通讯录支持用户变更、部门变更、角色变更和企业信息变更等回调事件，更多事件可参考事件订阅总览。

## 使用教程

钉钉提供了通讯录接口接入流程示例。

* [创建、获取、更新和删除企业员工](/zh/open/development/address-book-employee-operations)
* [创建、获取、更新和删除企业部门](/zh/open/development/operations-related-to-address-book-departments)
* [企业OA系统与钉钉通讯录实现同步](/zh/open/development/synchronization-between-enterprise-oa-system-and-dingtalk-address-book)
* 第三方个人小程序获取登录用户信息

## 名词解释

### 工号

工号对应的字段编码是job\_number，企业内员工的工号可以不唯一，所以不能作为员工在企业内的唯一标识。

企业管理员登录[钉钉管理后台](https://oa.dingtalk.io/)，在通讯录页面单击**员工姓名**可查看员工工号，工号字段是非必填字段。![通讯录概述1](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0538514561/p440185.png)

### unionId

用户在当前钉钉开放平台账号范围内的唯一标识，同一个钉钉开放平台账号可以包含多个开放应用，同时也包含ISV的套件应用及企业应用。

unionId可通过调用[查询用户详情](/zh/open/development/query-user-details)接口获取。

### 角色组和角色

企业内定义的角色组和角色，方便对员工身份信息进行管理，员工同时可拥有多个角色身份。

企业管理员登录[钉钉管理后台](https://oa.dingtalk.io/)，在**通讯录 > 内部通讯录管理**页面，单击**角色**可查看角色组和角色。![通讯录概述2](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0538514561/p440187.png)

### 通讯录扩展字段

通讯录可以添加扩展字段。

企业管理员登录[钉钉管理后台](https://oa.dingtalk.io/)，在**内部通讯录设置 > 通讯录信息** > **添加自定义字段**页面，新增自定义字段。![通讯录概述3](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0538514561/p440179.png)