Overview

This document helps you gain a comprehensive understanding of DingTalk Contacts. By reading this document, organization managers, IT leads, and developers can quickly grasp the capability boundaries of Contacts and lay the foundation for subsequent system integration and business innovation.

​

What is DingTalk Contacts

DingTalk Contacts is the core infrastructure for unified management of internal organizational information. It digitally represents the Organization Structure and User information of an Organization, providing users with the basic capability to quickly locate people and collaborate efficiently. For more feature details, see DingTalk User Guide - Organization Contacts.

​

How to view Contacts

​

Organization Admin perspective

Organization Admins can manage and view Contacts in the following ways:

• DingTalk Admin Console: Sign in to the DingTalk Admin Console, and go to the Internal Contacts module to perform full management and configuration of Contacts.
• Contacts Settings: Configure advanced features such as Contacts visibility rules, Custom fields, and Executive mode.

​

Regular users

Regular Organization Users can view Contacts through the following endpoints:

• DingTalk for PC: In the DingTalk PC client, click the Contacts tab to view the Organization Structure and contact details.
• DingTalk Mobile: In the DingTalk mobile App, go to the Contacts page to browse by Department or search by keyword.
• DingTalk for Web: Access Contacts features through the DingTalk web version.

​

Open capabilities overview

​

Open API list

Contacts provides extensive Open API capabilities. Developers can use the APIs to integrate Contacts with their business systems.

​

User contacts

​

Contacts permissions

​

User management

​

Department management

​

Role management

​

External contacts

​

Enterprise Account

​

Organization management

​

Contacts ID translation

​

Contacts visibility management

​

Callback event list

Contacts supports callback events such as user changes, Department changes, Role changes, and Organization information changes. For more events, see the event subscription overview.

​

Tutorials

DingTalk provides sample integration flows for Contacts APIs.

• Create, get, update, and delete organization employees
• Create, get, update, and delete organization departments
• Synchronize the enterprise OA system with DingTalk Contacts
• Get the signed-in user information from a third-party personal Mini program

​

Glossary

​

Employee ID

The Field code corresponding to Employee ID is job_number. The Employee ID of an Employee within an Organization does not have to be unique, so it cannot be used as a unique identifier for the Employee within the Organization. The Organization Admin signs in to the DingTalk Admin Console, and on the Contacts page, clicks the Employee Name to view the Employee ID. The Employee ID Field is Optional.

​

unionId

The unique identifier of a user within the scope of the current DingTalk Open Platform account. A single DingTalk Open Platform account can contain multiple open Apps, including ISV suite Apps and Internal apps. The unionId can be obtained by calling the Query user details API.

​

Role group and role

Role groups and Roles are defined within the Organization to facilitate the management of Employee identity information. An Employee can hold multiple Role identities at the same time. The Organization Admin signs in to the DingTalk Admin Console, goes to the Contacts > Internal Contacts Management page, and clicks Role to view role groups and Roles.

​

Contacts extension fields

You can add extension Fields to Contacts. The Organization Admin signs in to the DingTalk Admin Console, and goes to Internal Contacts Settings > Contacts Information > Add Custom Field to add Custom fields.