Update internal user information - DingTalk Help Center

Call this API to update the internal user information of a specified Enterprise Account. Only available to organizations that have purchased and enabled Enterprise Account.

Request

Basic information
HTTP URL	https://oapi.dingtalk.io/topapi/v2/user/update
HTTP Method	POST
Supported app types	appType-Internal app
Required permissions	permission-qyapi_manage_addresslist-Contacts data management permission

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	be3Fxxxx	The App credential used to call this API. Obtain it through the API for getting the access_token of an Internal app.

Request body

Name	Type	Required	Example	Description
userid	String	Yes	user123	The user ID of the employee.
name	String	No	Zhang San	Employee name. Up to 80 characters.
hide_mobile	Boolean	No	false	Whether to hide the phone number: - true: Hide. After the phone number is hidden, it is hidden on the Profile page, but you can still send DINGs and initiate DingTalk business calls to this employee. - false: Do not hide.
telephone	String	No	010-86123456-2345	Extension number. Up to 50 characters. Note The extension number is unique and cannot be duplicated within Your organization.
job_number	String	No	4	Employee ID. Up to 50 characters.
manager_userid	String	No	0001	The user ID of the direct manager.
title	String	No	Technical Director	Job Title. Up to 200 characters.
email	String	No	test@xxx.com	Employee Mail. Up to 50 characters. Note The employee Mail is unique and cannot be duplicated within Your organization.
org_email	String	No	test@xxx.com	The Enterprise Mail of the employee. Note This field takes effect only when the following condition is met: the employee’s Enterprise Mail has been enabled.
work_place	String	No	Future Park	Work Location. Up to 100 characters.
remark	String	No	Alias information	Alias. Up to 2000 characters.
dept_id_list	String	Yes	”2,3,4”	The list of department IDs the employee belongs to.
dept_order_list	DeptOrder[]	No		The sort order of the employee within the corresponding departments.
dept_id	Number	No	2	Department ID.
order	Number	No	1	The sort order of the employee within the department.
dept_title_list	DeptTitle[]	No		The Job Title of the employee within the corresponding departments.
dept_id	Number	No	2	Department ID.
title	String	No	Senior Product Manager	The Job Title of the employee within the department.
extension	String	No	`{"hobby":"travel","age":"24"}`	Extended attributes. Up to 2000 characters. Note - A maximum of 10 extended attributes can be displayed on mobile. - If 10 extended attribute fields are set for an employee, all 10 must be passed during the update, even if their values remain unchanged. If only 1 is passed, the other 9 will be cleared. - Before using this parameter, add the attribute in DingTalk Admin Console > Settings > Contacts information. - The value of this field supports link type input, and links support automatic replacement of variable wildcards. Currently supported wildcards are userid and corpid. Example: `[Desk number address](http://www.dingtalk.io?userid=#userid#&corpid=#corpid#)`.
ext_attrs_update_mode	Number	No	1	The update mode for Custom fields of extended attributes: - 0: Overwrite mode - 1: Append mode Default is Overwrite.
senior_mode	Boolean	No	false	Whether to enable Executive Mode. Default is false. - true: Enable. Note - When enabled, the phone number is hidden from all employees. - Regular employees cannot send DINGs or initiate DingTalk business calls to this user. - Executives can send DINGs and initiate DingTalk business calls to each other. - false: Do not enable.
hired_date	Number	No	1597573616828	Hire date, as a UNIX timestamp in milliseconds.
language	String	No	zh_CN	Contacts language. Values: - zh_CN: Chinese (Default). - en_US: English.
force_update_fields	String	No	manager_userid	Fields to force update. Supports clearing specified fields. Separate multiple fields with commas. Currently supported fields: `manager_userid`, `org_email`. Note - If org_email is included in the force update fields and the org_email parameter is empty, the binding between the employee and the Enterprise Mail will be removed, and the Enterprise Mail account will be frozen or deleted. - If org_email is included in the force update fields and the employee is already bound to another Enterprise Mail, the binding with the original Enterprise Mail will be removed, the original Enterprise Mail account will be frozen or deleted, and the employee will be bound to the new Enterprise Mail. - If org_email is included in the force update fields and the corresponding mailbox account is a public or service mailbox, the mailbox type will be converted to a regular mailbox, and the employee will be bound to the Enterprise Mail.
org_email_type	String	No	profession	The Enterprise Mail type for an Enterprise Account employee. - profession: Standard edition - base: Basic edition
loginId	String	No	loginId123	The sign-in name for the DingTalk Enterprise Account. Only DingTalk Enterprise Accounts can update this field. Single sign-on Enterprise Accounts are not supported. Note Do not include contact information such as phone numbers, email addresses, or links to avoid SMS messages being blocked by carriers.
init_password	String	No	init_password220	The initial password for the DingTalk Enterprise Account. Must be at least 8 characters. Note - Cannot consist entirely of letters or numbers. - Only DingTalk Enterprise Accounts can update this field. Single sign-on Enterprise Accounts are not supported. - Do not include contact information such as phone numbers, email addresses, or links to avoid SMS messages being blocked by carriers.
send_password_to_user	Boolean	No	false	Whether to send the account credentials. Default is false. - false: Do not send - true: Send Note - When this parameter is true, the `init_password` parameter is Required; otherwise, the credentials will not be sent. - When sending, an SMS message will be sent to the employee’s phone number or an email will be sent to the employee’s personal mailbox. - Only DingTalk Enterprise Accounts support setting this field. Single sign-on Enterprise Accounts are not supported.
exclusive_mobile	String	No	150xxxxxxx	The phone number of the Enterprise Account.
avatarMediaId	String	No	@lALPDfmVUw19YdrNA-jNA-g	When updating an Enterprise Account for the current organization, you can specify the Profile Photo MediaId. Only jpg and png formats are supported. Obtain it through the Upload media File API. Note Supports Custom Enterprise Accounts and single sign-on Enterprise Accounts.
nickname	String	No	Name	The Name of the Enterprise Account. Note Supports Custom Enterprise Accounts and single sign-on Enterprise Accounts.
dept_position_list	DeptPosition[]	No		Position information within the department.
extension_i18n	Json	No	`{"hobby":{"zh_CN":"travel","en_US":"travel","aJP":"travel"}}`	The internationalized values of the extended attributes.

Request example

curl -X POST "https://oapi.dingtalk.io/topapi/v2/user/update" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=9321cd22-5087-4456-969a-190ad398e925' \
-d 'userid=zhangsan' \
-d 'name=%E5%BC%A0%E4%B8%89' \
-d 'mobile=1851xxxx676' \
-d 'hide_mobile=false' \
-d 'telephone=010-86123456-2345' \
-d 'job_number=4' \
-d 'title=%E6%8A%80%E6%9C%AF%E6%80%BB%E7%9B%91' \
-d 'email=test%40xxx.com'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/update");
OapiV2UserUpdateRequest req = new OapiV2UserUpdateRequest();
req.setUserid("user001");
req.setName("John dingtalk");
req.setHideMobile(true);
req.setTelephone("456");
req.setJobNumber("456");
req.setManagerUserid("001");
req.setTitle("title");
req.setEmail("xxx@xxx.com");
req.setOrgEmail("1111");
req.setWorkPlace("Beijing");
req.setRemark("Alias");
req.setDeptIdList("486882146,609916162");
List<OapiV2UserUpdateRequest.DeptOrder> deptOrderList = new ArrayList<OapiV2UserUpdateRequest.DeptOrder>();
OapiV2UserUpdateRequest.DeptOrder deptOrder1 = new OapiV2UserUpdateRequest.DeptOrder();
deptOrder1.setDeptId(486882146l);
deptOrder1.setOrder(1L);
OapiV2UserUpdateRequest.DeptOrder deptOrder2 = new OapiV2UserUpdateRequest.DeptOrder();
deptOrder2.setDeptId(609916162l);
deptOrder2.setOrder(1L);
deptOrderList.add(deptOrder1);
deptOrderList.add(deptOrder2);
req.setDeptOrderList(deptOrderList);
List<OapiV2UserUpdateRequest.DeptTitle> deptTitleList = new ArrayList<OapiV2UserUpdateRequest.DeptTitle>();
OapiV2UserUpdateRequest.DeptTitle deptTitle1 = new OapiV2UserUpdateRequest.DeptTitle();
deptTitle1.setDeptId(486882146l);
deptTitle1.setTitle("Senior Product Manager");
OapiV2UserUpdateRequest.DeptTitle deptTitle2 = new OapiV2UserUpdateRequest.DeptTitle();
deptTitle2.setDeptId(609916162l);
deptTitle2.setTitle("Senior Product Manager");
deptTitleList.add(deptTitle1);
deptTitleList.add(deptTitle2);
req.setDeptTitleList(deptTitleList);
req.setExtension("{\"Hobby\":\"Travel\",\"Age\":\"24\"}");
req.setSeniorMode(false);
req.setHiredDate(1650351000000l);
req.setForceUpdateFields("manager_userid");
req.setLanguage("zh_CN");
req.setOrgEmailType("profession");
req.setLoginId("test");
req.setExclusiveMobile("183xxxx");
req.setAvatarMediaId("@lADPDfYH3A-xxxx");
req.setNickname("Test");
OapiV2UserUpdateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiV2UserUpdateRequest("https://oapi.dingtalk.io/topapi/v2/user/update")

req.userid="zhangsan"
req.name="John"
req.mobile="13800138000"
req.hide_mobile=false
req.telephone="010-86123456-2345"
req.job_number="4"
req.title="Technical Director"
req.email="test@xxx.com"
req.org_email="test@xxx.com"
req.work_place="Future park"
req.remark="Alias"
req.dept_id_list="2,3,4"
req.dept_order_list="[2,1]"
req.dept_title_list="[2,"Senior Product Manager"]"
req.senior_mode=false
req.hired_date=1597573616828
req.language="zh_CN"
req.init_password="Password123"
req.loginId="loginId123"
req.dept_position_list="[2,"Senior Product Manager",true,"Future park","100",{},{}]"
req.org_email_type="profession"
req.force_update_fields="manager_userid"
req.manager_userid="0001"
req.exclusive_mobile="+86-19812341234"
req.exclusive_mobile_verify_status="verified/notVerified"
req.nickname="Name"
req.avatarMediaId="@lALPDfmVUw19YdrNA-jNA-g"
req.ext_attrs_update_mode=0
req.ext_attrs="["emp:xxx",{"images":["https://img.alicdn.com/imgextra/i2/O1CN01IVwD5w1mqnRxmUBng_!!6000000005006-2-tps-64-64.png"],"text":"Click to visit the DingTalk official website","url":"www.dingtalk.io"}]"
req.gender="F"
req.limited=false
req.has_subordinate=false
req.dept_name="Department1-Department11-Department111"
req.flower_name="Nickname"
req.send_password_to_user=false
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

PHP

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2UserUpdateRequest;
$req->setUserid("zhangsan");
$req->setName("John");
$req->setMobile("13800138000");
$req->setHideMobile("false");
$req->setTelephone("010-86123456-2345");
$req->setJobNumber("4");
$req->setTitle("Technical Director");
$req->setEmail("test@xxx.com");
$req->setOrgEmail("test@xxx.com");
$req->setWorkPlace("Future park");
$req->setRemark("Alias");
$req->setDeptIdList("2,3,4");
$dept_order_list = new DeptOrder;
$req->setDeptOrderList(array($dept_order_list));
$dept_title_list = new DeptTitle;
$req->setDeptTitleList(array($dept_title_list));
$req->setSeniorMode("false");
$req->setHiredDate("1597573616828");
$req->setLanguage("zh_CN");
$req->setInitPassword("Password123");
$req->setLoginId("loginId123");
$dept_position_list = new DeptPosition;
$req->setDeptPositionList(array($dept_position_list));
$req->setOrgEmailType("profession");
$req->setForceUpdateFields("manager_userid");
$req->setManagerUserid("0001");
$req->setExclusiveMobile("+86-19812341234");
$req->setExclusiveMobileVerifyStatus("verified/notVerified");
$req->setNickname("Name");
$req->setAvatarMediaId("@lALPDfmVUw19YdrNA-jNA-g");
$req->setExtAttrsUpdateMode("0");
$ext_attrs = new EmpExtAttr;
$req->setExtAttrs(array($ext_attrs));
$req->setGender("F");
$req->setLimited("false");
$req->setHasSubordinate("false");
$req->setDeptName("Department1-Department11-Department111");
$req->setFlowerName("Nickname");
$req->setSendPasswordToUser("false");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/v2/user/update");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/update");
OapiV2UserUpdateRequest req = new OapiV2UserUpdateRequest();
req.Userid = "zhangsan";
req.Name = "John";
req.Mobile = "185xxxx676";
req.HideMobile = false;
req.Telephone = "010-86123456-2345";
req.JobNumber = "4";
req.Title = "Technical Director";
req.Email = "test@xxx.com";
req.OrgEmail = "test@xxx.com";
req.WorkPlace = "Future park";
req.Remark = "Alias";
req.DeptIdList = "\"2,3,4\"";
OapiV2UserUpdateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

Name	Type	Example	Description
errcode	Number	0	Return code. 0 indicates Success.
errmsg	String	User not found	The error message returned when the call failed.

Response body example

{
  "errcode":0,
  "errmsg":"ok",
  "request_id":"55o5i31j4cg8"
}

Error codes

If an error occurs when calling this API, refer to the Global error codes document for solutions.

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes