API call description
This API supports creating either a regular user or an Enterprise Account user. Because parameter usage differs significantly between the two scenarios, the documentation is split by account type for clarity:- To create a regular user, refer to this article.
- To create an Enterprise Account user (only available to organizations that have purchased and enabled this feature), refer to the following articles:
Request
| Basic information | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/v2/user/create |
| 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 | BE3xxxx | The app credential for calling this API. Obtain it by calling the API that retrieves the access_token of an internal app. |
Request body
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| userid | String | No | zhangsan | The unique identifier of the employee (cannot be modified). It must be unique within your organization. The length must be 1 to 64 characters. If not specified, a userid is automatically generated. |
| name | String | Yes | Zhang San | The employee name. Maximum 80 characters. |
| mobile | String | Yes | 185xxxx | The mobile number. It must be unique within your organization and cannot be duplicated. - For international numbers or numbers from Hong Kong (China), Macao (China), or Taiwan (China), use the format +xx-xxxxxx. - If the company is registered outside the Chinese mainland, use the format +86-xxxxxx when adding a user. Note Sign in to the DingTalk Admin Console to view the organization’s registered address. |
| hide_mobile | Boolean | No | false | Whether to hide the mobile number: - true: Hide. After the mobile number is hidden, it is not displayed on the Profile page, but other users can still send DINGs and initiate free DingTalk business calls. - false: Do not hide. |
| telephone | String | No | 010-86123456-2345 | The extension number. Maximum 50 characters. Note Extension numbers must be unique within your organization. |
| job_number | String | No | 4 | The Employee ID. Maximum 50 characters. |
| title | String | No | Technical Director | The Job Title. Maximum 200 characters. |
| String | No | test@xxx.com | The personal Mail of the employee. Maximum 50 characters. Note Employee mail addresses must be unique within your organization. | |
| org_email | String | No | test@xxx.com | The Enterprise Mail of the employee. Maximum 100 characters. Note This field takes effect only when Enterprise Mail has been activated for the employee. |
| org_email_type | String | No | profession | The Enterprise Mail type of the employee. - profession: Standard - base: Basic |
| work_place | String | No | Future Park | The Work Location. Maximum 100 characters. |
| remark | String | No | Alias | The alias. Maximum 2000 characters. |
| dept_id_list | String | Yes | ”2,3,4” | The list of department IDs the employee belongs to. Up to 100 department IDs can be passed per call. |
| dept_order_list | Object[] | No | The sort order of the employee within the corresponding departments. | |
| dept_id | Number | No | 2 | The department ID. |
| order | Number | No | 1 | The sort order of the employee within the department. |
| dept_title_list | Object[] | No | The Job Title of the employee within the corresponding departments. | |
| dept_id | Number | No | 2 | The department ID. |
| title | String | No | Senior Product Manager | The Job Title of the employee within the department. |
| extension | Object | No | {"Hobby":"Travel","Age":"24"} | Extension attributes. Multiple attributes can be configured. Maximum 2000 characters. Note - Up to 10 extension attributes can be displayed on a mobile device. - Before using this parameter, add the attribute in the DingTalk Admin Console > Internal Contacts Settings > Member Field Management, and then call the API to set its value. For details, see About the extension parameter below. - The value of this field supports link types, and links support automatic replacement of variable wildcards. Currently supported wildcards include: userid and corpid. For example: {"Hobby":"[Hobby](http://www.dingtalk.io?userid=#userid#&corpid=#corpid#)"} - Important: Directly adding a new attribute will overwrite the existing attribute values. Retrieve the existing attributes first, append the new attribute to them, and then perform a full update. |
| senior_mode | Boolean | No | false | Whether to enable executive mode. Default: false. - true: Enable. Note - When enabled, the mobile number is hidden from all employees. - Regular employees cannot send DINGs or initiate DingTalk business calls to the user. - Executives can send DINGs and initiate DingTalk business calls to each other. - false: Do not enable. |
| hired_date | Number | No | 1597573616828 | The hire date, as a Unix timestamp in milliseconds. |
| manager_userid | String | No | 001 | The userId of the direct manager. |
| login_email | String | No | test@xxx.com | The sign-in mail address. Note This field applies only to mail accounts. Setting this field for non-mail accounts has no effect. |
| dept_position_list | DeptPosition[] | No | The position information within the department. | |
| extension_i18n | Json | No | {"Hobby": {"zh_CN": "Travel", "en_US": "Travel", "aJP": "Trip"}} | The internationalized values of extension attributes. |
Request example
curl -X POST "https://api.dingtalk.io/topapi/v2/user/create" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=1c016742-9383-4276-beb1-ebb375acc454' \
-d 'name=John' \
-d 'mobile=13800138000' \
-d 'dept_id_list=%5C%222%2C3%2C4%5C%22'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/create");
OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
req.setUserid("002");
req.setName("Test");
req.setSeniorMode(false);
req.setMobile("184806*****");
req.setTitle("Faculty");
req.setEmail("test@xx.com");
req.setOrgEmail("test@xxx.com");
req.setOrgEmailType("profession");
req.setDeptIdList("1");
ArrayList<OapiV2UserCreateRequest.DeptTitle> deptTitles = new ArrayList<>();
OapiV2UserCreateRequest.DeptTitle deptTitle = new OapiV2UserCreateRequest.DeptTitle();
deptTitle.setDeptId(1L);
deptTitle.setTitle("Test");
OapiV2UserCreateRequest.DeptTitle deptTitle1 = new OapiV2UserCreateRequest.DeptTitle();
deptTitle1.setDeptId(1L);
deptTitle1.setTitle("Specialist");
deptTitles.add(deptTitle);
deptTitles.add(deptTitle1);
req.setDeptTitleList(deptTitles);
req.setHideMobile(false);
req.setTelephone("010-8xxxxx6-2345");
req.setJobNumber("100828");
req.setHiredDate(1615219200000L);
req.setWorkPlace("Future Park");
req.setRemark("Remarks");
List<OapiV2UserCreateRequest.DeptOrder> deptOrderList = new ArrayList<OapiV2UserCreateRequest.DeptOrder>();
OapiV2UserCreateRequest.DeptOrder deptOrder = new OapiV2UserCreateRequest.DeptOrder();
deptOrder.setDeptId(1L);
deptOrder.setOrder(1L);
OapiV2UserCreateRequest.DeptOrder deptOrder1 = new OapiV2UserCreateRequest.DeptOrder();
deptOrder1.setDeptId(1L);
deptOrder1.setOrder(1L);
deptOrderList.add(deptOrder);
deptOrderList.add(deptOrder1);
req.setDeptOrderList(deptOrderList);
req.setExtension("{\"Hobby\":\"[Hobby](http://test.com?userid=#userid#&corpid=#corpid#)\"}");
req.setManagerUserid("001");
req.setLoginEmail("test@xxx.com");
OapiV2UserCreateResponse rsp = client.execute(req, "");
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiV2UserCreateRequest("https://api.dingtalk.io/topapi/v2/user/create")
req.userid="zhangsan"
req.name="John"
req.mobile="13800138000"
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="Remarks"
req.dept_id_list="2,3,4"
req.check_user_protect=true
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 OapiV2UserCreateRequest;
$req->setUserid("zhangsan");
$req->setName("John");
$req->setMobile("13800138000");
$req->setTelephone("010-86123456-2345");
$req->setTitle("Technical Director");
$req->setEmail("test@xxx.com");
$req->setWorkPlace("Future Park");
$req->setRemark("Remarks");
$req->setDeptIdList("\"2,3,4\"");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/create");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/create");
OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
req.Userid = "zhangsan";
req.Name = "John";
req.Mobile = "13800138000";
req.Title = "Technical Director";
req.Email = "test@xxx.com";
req.OrgEmail = "test@xxx.com";
req.WorkPlace = "Future Park";
req.Remark = "Remarks";
req.DeptIdList = "\"2,3,4\"";
OapiV2UserCreateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Response
Response body
| Name | Type | Example | Description |
|---|---|---|---|
| errcode | Number | 0 | The error code. 0 indicates success. |
| errmsg | String | ok | The error message. |
| result | Object | The returned result. | |
| userid | String | zhangsan | The employee ID. |
| unionId | String | xxxx | The unique ID of the employee. |
Response body example
{
"errcode":"0",
"result":{
"unionId":"xxxx",
"userid":"zhangsan"
},
"errmsg":"ok"
}
Error codes
If an error occurs when calling this API, refer to the Global error codes document for solutions based on the error message.About the extension parameter
To display the user attributes configured in the extension field, complete the following steps.- Sign in to the DingTalk Admin Console.
- Click Internal Contacts Settings, then click Member Field Management > Add Custom Field.