Developer GuideAPI 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://api.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. |
| 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://api.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'
DingTalkClient client = new DefaultDingTalkClient("https://api.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());
import dingtalk.api
req=dingtalk.api.OapiV2UserUpdateRequest("https://api.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)
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://api.dingtalk.io/topapi/v2/user/update");
IDingTalkClient client = new DefaultDingTalkClient("https://api.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"
}