开发指南接口调用说明
调用本接口可以实现更新普通账号用户信息或更新企业账号用户信息。由于在调用时参数使用有较多区别，为便于开发者查看，按照新用户的账号类型进行拆分优化：- 更新普通用户信息，接口说明文档请查看本文介绍。
- 更新企业账号用户信息，接口说明文档请参见更新企业账号用户信息。
请求
| 基本信息 | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/v2/user/update |
| HTTP Method | POST |
| 支持的应用类型 | appType-企业内部应用 |
| 权限要求 | permission-qyapi_manage_addresslist-通讯录数据管理权限 |
查询参数
| 名称 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| access_token | String | 是 | be3Fxxxx | 调用该接口的应用凭证，通过获取企业内部应用的access_token接口获取。 |
请求体
| 名称 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| userid | String | 是 | user123 | 员工的userId。 |
| name | String | 否 | 张三 | 员工名称，长度最大80个字符。 |
| hide_mobile | Boolean | 否 | false | 是否号码隐藏： - true：隐藏 隐藏手机号后，手机号在个人资料页隐藏，但仍可对其发DING、发起钉钉免费商务电话。 - false：不隐藏 |
| telephone | String | 否 | 010-86123456-2345 | 分机号，长度最大50个字符。 说明 分机号是唯一的，企业内不能重复。 |
| job_number | String | 否 | 4 | 员工工号，长度最大50个字符。 |
| manager_userid | String | 否 | 0001 | 直属主管的userId。 |
| title | String | 否 | 技术总监 | 职位，长度最大200个字符。 |
| String | 否 | test@xxx.com | 员工邮箱，长度最大50个字符。 说明 员工邮箱是唯一的，企业内不能重复。 | |
| org_email | String | 否 | test@xxx.com | 员工的企业邮箱。 说明 需满足以下条件，此字段才生效：员工的企业邮箱已开通。 |
| work_place | String | 否 | 未来park | 办公地点，长度最大100个字符。 |
| remark | String | 否 | 备注信息 | 备注，长度最大2000个字符。 |
| dept_id_list | String | 否 | ”2,3,4” | 所属部门ID列表。 |
| dept_order_list | DeptOrder[] | 否 | 员工在对应的部门中的排序。 | |
| dept_id | Number | 否 | 2 | 部门ID。 |
| order | Number | 否 | 1 | 员工在部门中的排序。数值越大，排序越靠前。 |
| extension | String | 否 | {"爱好":"旅游","年龄":"24"} | 扩展属性，长度最大 2000 个字符。 说明 - 手机上最多只能显示 10 个扩展属性。 - 如果给员工设置有 10 个扩展属性字段，更新时即使扩展属性字段值没变，也必须要将 10 个扩展属性字段都传进去。如果只传其中 1 个，那么剩下 9 个字段都会被清空。 - 在使用该参数前，需要先在钉钉管理后台 > 通讯录 > 内部通讯录设置 > 成员字段管理增加该属性。 - 该字段的值支持链接类型填写，同时链接支持变量通配符自动替换，目前支持通配符有：userid 和 corpid。示例：[工位地址](http://www.dingtalk.io?userid=#userid#&corpid=#corpid#)。 |
| ext_attrs_update_mode | Number | 否 | 1 | 拓展属性自定义字段更新模式： - 0：覆盖方式 - 1：追加方式 默认是覆盖。 |
| senior_mode | Boolean | 否 | false | 是否开启高管模式，默认值false。 - true：开启。 说明 - 开启后，手机号码对所有员工隐藏。 - 普通员工无法对其发DING、发起钉钉商务电话。 - 高管之间可以发DING、发起钉钉商务电话。 - false：不开启。 |
| hired_date | Number | 否 | 1597573616828 | 入职时间，UNIX时间戳，单位毫秒。 |
| language | String | 否 | zh_CN | 通讯录语言，取值。 - zh_CN：中文（默认值）。 - en_US：英文。 |
| force_update_fields | String | 否 | manager_userid | 强制更新的字段，支持清空指定的字段，多个字段之间使用逗号分隔。目前支持字段: manager_userid。 |
| dept_position_list | DeptPosition[] | 否 | 部门内任职信息。 | |
| extension_i18n | Json | 否 | {"爱好": {"zh_CN": "旅游", "en_US": "travel", "aJP": "旅行"}} | 扩展属性的国际化值。 |
请求示例
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=%E5%BC%A0%E4%B8%89' \
-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("张三");
req.setHideMobile(false);
req.setTelephone("010-86123456-2345");
req.setJobNumber("4");
req.setManagerUserid("0001");
req.setTitle("技术总监");
req.setEmail("test@xxx.com");
req.setOrgEmail("test@xxx.com");
req.setWorkPlace("未来park");
req.setRemark("备注备注");
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("{\"爱好\":\"旅游\",\"年龄\":\"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="张三"
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("张三");
$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 = "张三";
req.Mobile = "13800138000";
req.HideMobile = false;
OapiV2UserUpdateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
响应
响应体
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| errcode | Number | 0 | 返回码，0代表成功。 |
| errmsg | String | 找不到该用户 | 调用失败时返回的错误信息。 |
响应体示例
{
"errcode": 0,
"request_id": "55o5i31j4cg8"
}