Update user information - DingTalk Help Center

Call this API to update the information of a specified user.

API call description

This API updates the information of a regular user account or an Enterprise Account user. Because the parameter usage differs significantly between these two scenarios, the documentation is split by account type for easier reference:

To update regular user information, refer to this document.
To update Enterprise Account user information, refer to Update Enterprise Account user information.

Request

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

Query parameter

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	The employee name. Maximum length: 80 characters.
hide_mobile	Boolean	No	false	Whether to hide the phone number: - true: Hide. Once hidden, the phone number is hidden on the profile page, but other users can still send DINGs and place free DingTalk business calls to this user. - false: Do not hide.
telephone	String	No	010-86123456-2345	The extension number. Maximum length: 50 characters. Note The extension number must be unique within your organization.
job_number	String	No	4	The employee ID. Maximum length: 50 characters.
manager_userid	String	No	0001	The user ID of the direct manager.
title	String	No	Technical Director	The job title. Maximum length: 200 characters.
email	String	No	test@xxx.com	The employee mail. Maximum length: 50 characters. Note The employee mail must be unique within your organization.
org_email	String	No	test@xxx.com	The Enterprise Mail of the employee. Note This field takes effect only when the employee’s Enterprise Mail has been enabled.
work_place	String	No	Future Park	The work location. Maximum length: 100 characters.
remark	String	No	Remark information	The alias. Maximum length: 2,000 characters.
dept_id_list	String	No	”2,3,4”	The list of department IDs to which the user belongs.
dept_order_list	DeptOrder[]	No		The sort order of the employee within each department.
dept_id	Number	No	2	The department ID.
order	Number	No	1	The sort order of the employee within the department. A larger value places the employee higher in the list.
extension	Number	No	`{"Hobby":"Travel","Age":"24"}`	The extension attributes. Maximum length: 2,000 characters. Note - At most 10 extension attributes can be displayed on mobile devices. - If an employee has 10 extension attribute fields configured, all 10 fields must be passed during an update, even if their values have not changed. If you pass only one field, the other nine will be cleared. - Before using this parameter, add the attribute in DingTalk Admin Console > Contacts > Internal contacts settings > User field management. - The value of this field supports link types, and the link supports automatic replacement of variable wildcards. The 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 extension attribute fields: - 0: Overwrite mode - 1: Append mode The default is overwrite.
senior_mode	Boolean	No	false	Whether to enable executive mode. Default: false. - true: Enable. Note - When enabled, the phone number is hidden from all employees. - Regular employees cannot send DINGs or place DingTalk business calls to this user. - Executives can send DINGs and place DingTalk business calls to each other. - false: Do not enable.
hired_date	Number	No	1597573616828	The hire date. UNIX timestamp, in milliseconds.
language	String	No	zh_CN	The Contacts language: - 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 field: `manager_userid`.
dept_position_list	DeptPosition[]	No		The position information within the department.
extension_i18n	Json	No	`{"Hobby": {"zh_CN": "旅游", "en_US": "travel", "aJP": "旅行"}}`	The internationalized values of extension 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=c6c3c34d-23dd-4da7-9901-0af1ebceaf80' \
-d 'name=John' \
-d 'telephone=010-86123456-2345' \
-d 'hide_mobile=false' \
-d 'userid=zhangsan'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/update");
OapiV2UserUpdateRequest req = new OapiV2UserUpdateRequest();
req.setUserid("zhangsan");
req.setName("John");
req.setHideMobile(false);
req.setTelephone("010-86123456-2345");
req.setJobNumber("4");
req.setManagerUserid("0001");
req.setTitle("Technical Director");
req.setEmail("test@xxx.com");
req.setOrgEmail("test@xxx.com");
req.setWorkPlace("Future Park");
req.setRemark("Remark");
req.setDeptIdList("2,3,4");
List<DeptOrder> list2 = new ArrayList<DeptOrder>();
DeptOrder obj3 = new DeptOrder();
list2.add(obj3);
obj3.setDeptId(2L);
obj3.setOrder(1L);
req.setDeptOrderList(list2);
req.setExtension("{\"Hobby\":\"Travel\",\"Age\":\"24\"}");
req.setSeniorMode(false);
req.setHiredDate(1597573616828L);
req.setLanguage("zh_CN");
req.setForceUpdateFields("manager_userid");
OapiV2UserUpdateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

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

req.userid="zhangsan"
req.name="John"
req.hide_mobile=false
req.telephone="010-86123456-2345"

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->setHideMobile("false");
$req->setTelephone("010-86123456-2345");
$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 = "13800138000";
req.HideMobile = false;
OapiV2UserUpdateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

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

Response body example

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

Error codes

If an error is returned when you call this API, refer to the Global error codes document to find a solution.

​API call description

​Request

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes