Create a DingTalk-built enterprise account

Call this API to create a DingTalk-built enterprise account user. This API is only available to organizations that have purchased and enabled this feature.

Request

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

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	BE3xxxx	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	No	zhangsan	The unique identifier of the employee (cannot be modified), 1 to 64 characters in length. Note - Must be unique within your organization. - If not specified, a userId is generated automatically.
exclusive_account	Boolean	Yes	true	Must be set to true, indicating that an enterprise account is to be created. Note Applies only to enterprise accounts.
exclusive_account_type	String	Yes	dingtalk	Must be set to dingtalk, indicating a DingTalk-built enterprise account. Note Applies only to DingTalk-built enterprise accounts.
login_id	String	Yes	login_id3	The login name of the DingTalk-built enterprise account. Note Do not include information such as phone numbers or email links to avoid sign-up SMS messages being blocked by carriers.
init_password	String	Yes	init_password220	The initial password of the DingTalk-built enterprise account. The initial password must contain at least 8 characters. Note - The password cannot consist entirely of letters or digits. - Do not include information such as phone numbers, emails, or links to avoid sign-up SMS messages being blocked by carriers.
send_password_to_user	Boolean	No	false	Whether to send the account credentials. Default value: false. - false: Do not send. - true: Send. Note - When sending, an SMS message is sent to the employee’s phone number or an email is sent to the personal email address. - When this parameter is set to true, the `init_password` parameter is required; otherwise, no message is sent.
name	String	Yes	Zhang San	The employee name, with a maximum length of 80 characters.
dept_id_list	String	Yes	”2,3,4”	The list of department IDs the employee belongs to. Separate multiple department IDs with commas (`,`). A maximum of 100 department IDs can be passed per call.
telephone	String	No	010-86123456-2345	The extension number, with a maximum length of 50 characters. Note The extension number must be unique within your organization.
job_number	String	No	4	The Employee ID, with a maximum length of 50 characters.
title	String	No	Technical Director	The Job Title, with a maximum length of 200 characters.
email	String	No	test@xxx.com	The employee’s personal email, with a maximum length of 50 characters. Note The employee’s email must be unique within your organization.
org_email	String	No	test@xxx.com	The employee’s Enterprise Mail, with a maximum length of 100 characters. Note This field takes effect only when the employee has enabled Enterprise Mail.
org_email_type	String	No	profession	The type of the employee’s Enterprise Mail: - profession: Standard edition. - base: Basic edition.
work_place	String	No	Future Park	The Work Location, with a maximum length of 100 characters.
remark	String	No	Alias information	The Alias, with a maximum length of 2,000 characters.
dept_order_list	Object[]	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 indicates a higher position.
dept_title_list	Object[]	No		The Job Title of the employee within each department.
dept_id	Number	No	2	The department ID.
title	String	No	Senior Product Manager	The Job Title of the employee within the department.
extension	String	No	`{"Hobby":"Travel","Age":"24"}`	Extended attributes. Multiple attributes can be set, with a maximum length of 2,000 characters. Note - A maximum of 10 extended attributes can be displayed on mobile. - Before using this parameter, add the attribute in the DingTalk admin console first, and then call the API to assign a value. - The value of this field supports link types. Links support variable wildcards that are automatically replaced. Currently supported wildcards are userid and corpid. Example: `{"Hobby":"[Hobby](http://www.dingtalk.io?userid=#userid#&corpid=#corpid#)"}`.
senior_mode	Boolean	No	false	Whether to enable executive mode. Default value: false. - true: Enable. Note - When enabled, the phone number is hidden from all employees. - Regular employees cannot send DINGs or initiate DingTalk business calls to executives. - Executives can send DINGs and initiate DingTalk business calls to each other. - false: Do not enable.
hired_date	Number	No	1597573616828	The hire date, in Unix timestamp format (in milliseconds).
manager_userid	String	No	001	The userId of the direct manager.
exclusive_mobile	String	No	+86-13412341234	The phone number of the enterprise account. Note Applies only to enterprise accounts.
avatarMediaId	String	No	@lALPDfmVUw19YdrNA-jNA-g	When creating an enterprise account for your organization, you can specify the Profile Photo MediaId. Only jpg and png formats are supported. Obtain it by calling the Upload media file API. Note Applies only to enterprise accounts.
nickname	String	No	Name	When creating an enterprise account for your organization, you can specify the Name. Note Applies only to enterprise accounts.

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=3e4fcfdc-0d84-4124-9600-9456f89a42ef' \
-d 'exclusive_account_type=dingtalk' \
-d 'login_id=login_id3' \
-d 'extension=%7B%5C%22%E7%88%B1%E5%A5%BD%5C%22%3A%5C%22%E6%97%85%E6%B8%B8%5C%22%2C%5C%22%E5%B9%B4%E9%BE%84%5C%22%3A%5C%2224%5C%22%7D' \
-d 'exclusive_account=true' \
-d 'manager_userid=001' \
-d 'remark=%E5%A4%87%E6%B3%A8%E5%A4%87%E6%B3%A8' \
-d 'telephone=010-86123456-2345' \
-d 'hired_date=1597573616828' \
-d 'title=%E6%8A%80%E6%9C%AF%E6%80%BB%E7%9B%91' \
-d 'org_email_type=profession' \
-d 'userid=zhangsan' \
-d 'avatarMediaId=%40lALPDfmVUw19YdrNA-jNA-g' \
-d 'dept_title_list=null' \
-d 'work_place=%E6%9C%AA%E6%9D%A5park' \
-d 'dept_order_list=null' \
-d 'senior_mode=false' \
-d 'org_email=test%40xxx.com' \
-d 'name=%E5%BC%A0%E4%B8%89' \
-d 'nickname=%E6%98%B5%E7%A7%B0' \
-d 'exclusive_mobile=%2B86-13412341234' \
-d 'dept_id_list=%5C%222%2C3%2C4%5C%22' \
-d 'job_number=4' \
-d 'init_password=init_password220' \
-d 'email=test%40xxx.com'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/create");
OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
req.setUserid("123456789");
req.setExclusiveAccount(true);
req.setExclusiveAccountType("dingtalk");
req.setLoginId("xiaodingding");
req.setInitPassword("12345678dingding");
req.setName("DingTalk-built enterprise account");
req.setDeptIdList("486882146,609916162");
req.setTelephone("123");
req.setJobNumber("123");
req.setTitle("Technical Director");
req.setEmail("test@xxx.com");
req.setOrgEmail("ceshi2");
req.setOrgEmailType("base");
req.setWorkPlace("Beijing");
req.setRemark("Alias information");
OapiV2UserCreateRequest.DeptOrder deptOrder1 = new OapiV2UserCreateRequest.DeptOrder();
deptOrder1.setDeptId(486882146L);
deptOrder1.setOrder(2L);
OapiV2UserCreateRequest.DeptOrder deptOrder2 = new OapiV2UserCreateRequest.DeptOrder();
deptOrder2.setDeptId(609916162L);
deptOrder2.setOrder(1L);
ArrayList<OapiV2UserCreateRequest.DeptOrder> deptOrderList = new ArrayList<>();
deptOrderList.add(deptOrder1);
deptOrderList.add(deptOrder2);
req.setDeptOrderList(deptOrderList);
OapiV2UserCreateRequest.DeptTitle deptTitle1 = new OapiV2UserCreateRequest.DeptTitle();
deptTitle1.setTitle("Test");
deptTitle1.setDeptId(486882146L);
OapiV2UserCreateRequest.DeptTitle deptTitle2 = new OapiV2UserCreateRequest.DeptTitle();
deptTitle2.setTitle("Director");
deptTitle2.setDeptId(609916162L);
ArrayList<OapiV2UserCreateRequest.DeptTitle> deptTitleList = new ArrayList<>();
deptTitleList.add(deptTitle1);
deptTitleList.add(deptTitle2);
req.setDeptTitleList(deptTitleList);
req.setExtension("{\"Hobby\":\"Travel\",\"Age\":\"24\"}");
req.setSeniorMode(false);
req.setHiredDate(1650351000000l);
req.setManagerUserid("001");
req.setExclusiveMobile("150xxxx");
req.setAvatarMediaId("@lADPDfYH3A-xxxx");
req.setNickname("Name1");
OapiV2UserCreateResponse rsp = client.execute(req, accessToken);
System.out.println(rsp.getBody());

Python

# -*- coding: utf-8 -*-
import dingtalk.api

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

req.userid="zhangsan"
req.name="John"
req.telephone="010-86123456-2345"
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="Alias information"
req.dept_id_list=""2,3,4""
req.dept_order_list=""
req.dept_title_list=""
req.extension="{\"Hobby\":\"Travel\",\"Age\":\"24\"}"
req.senior_mode=false
req.hired_date=1597573616828
req.exclusive_account=false
req.exclusive_account_type="dingtalk"
req.login_id="login_id3"
req.init_password="init_password220"
req.org_email_type="profession"
req.manager_userid="001"
req.exclusive_mobile="+86-13412341234"
req.outer_exclusive_corpid="corpid"
req.outer_exclusive_userid="userid"
req.avatarMediaId="@lALPDfmVUw19YdrNA-jNA-g"
req.nickname="Name"
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->setExclusiveAccount("true");
$req->setExclusiveAccountType("dingtalk");
$req->setLoginId("login_id3");
$req->setInitPassword("init_password220");
$req->setName("John");
$req->setDeptIdList("\"2,3,4\"");
$req->setTelephone("010-86123456-2345");
$req->setJobNumber("4");
$req->setTitle("Technical Director");
$req->setEmail("test@xxx.com");
$req->setOrgEmail("test@xxx.com");
$req->setWorkPlace("Future Park");
$req->setRemark("Alias information");
$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.Telephone = "010-86123456-2345";
req.JobNumber = "4";
req.Title = "Technical Director";
req.Email = "test@xxx.com";
req.OrgEmail = "test@xxx.com";
req.WorkPlace = "Future Park";
req.Remark = "Alias information";
req.DeptIdList = "\"2,3,4\"";
req.ExclusiveAccount = true;
req.ExclusiveAccountType = "dingtalk";
req.LoginId = "login_id3";
req.InitPassword = "init_password220";
req.OrgEmailType = "profession";
req.ManagerUserid = "001";
req.AvatarMediaId = "@lALPDfmVUw19YdrNA-jNA-g";
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 is returned when calling this API, refer to the Global error codes document to find the solution based on the error message.

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes