Create a user - DingTalk Help Center

Call this API to create a new user.

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://oapi.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.
email	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://oapi.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'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.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());

Python

import dingtalk.api

req=dingtalk.api.OapiV2UserCreateRequest("https://oapi.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)

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 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://oapi.dingtalk.io/topapi/v2/user/create");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.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.

​API call description

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes

​About the extension parameter