Invite an Enterprise Account from another organization

Call this API to add an Enterprise Account from another organization into your organization.

API call description

Adding an Enterprise Account from another organization into your organization is only available to organizations that have purchased and activated this feature. Note the following when calling this API to add an Enterprise Account from another organization into your organization:

This API does not support adding non-Enterprise Accounts from other organizations.
The other organization must call the Authorize an Enterprise Account to join multiple organizations API to authorize their Enterprise Account to join your organization. Once authorization is complete, the other organization has allowed your organization to add their Enterprise Account into your organization.
After this API call succeeds, the Enterprise Account from the other organization is added directly into your organization. No additional confirmation from the Enterprise Account is required. (Once the authorization in step 2 is complete, the other organization is considered to have accepted, and no further account-level acceptance is needed.)

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 used to call this API. Obtain it through the API for obtaining 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). Length: 1–64 characters. Notes - Must be unique within Your organization. - If not provided, a user ID is generated automatically.
outer_exclusive_corpid	String	Yes	ding12345	The organization ID to which the Enterprise Account to be added belongs.
outer_exclusive_userid	String	Yes	user01	The user ID to which the Enterprise Account to be added belongs.
name	String	Yes	Zhang San	The Employee name. Maximum length: 80 characters.
dept_id_list	String	Yes	”2,3,4”	The list of Department IDs the Employee belongs to. Separate multiple Department IDs with an English comma `,`. A maximum of 100 Department IDs can be passed per call.
telephone	String	No	010-86123456-2345	The extension number. Maximum length: 50 characters. Notes The extension number is unique and cannot be repeated within Your organization.
job_number	String	No	4	The Employee ID. Maximum length: 50 characters.
title	String	No	Technical Director	The Job Title. Maximum length: 200 characters.
email	String	No	test@xxx.com	The Employee’s personal Mail. Maximum length: 50 characters. Notes The Employee Mail is unique and cannot be repeated within Your organization.
org_email	String	No	test@xxx.com	The Employee’s Enterprise Mail. Maximum length: 100 characters. Notes This field only takes effect when the Employee has activated Enterprise Mail.
org_email_type	String	No	profession	The Enterprise Mail Type of the Employee: - profession: Standard edition. - base: Basic edition.
work_place	String	No	Future Park	The Work Location. Maximum length: 100 characters.
remark	String	No	Alias information	The Alias. Maximum length: 2000 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 means a higher position in the Sort order.
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"}`	Extension Attributes. Multiple attributes can be set. Maximum length: 2000 characters. Notes - A maximum of 10 extension attributes can be displayed on mobile. - Before using this parameter, add the attribute in the DingTalk Admin Console, then call the API to assign values. - This field supports Link type values. Links also support variable wildcards for automatic replacement. Currently supported wildcards are userid and corpid. For example: `{"hobby":"[hobby](http://www.dingtalk.io?userid=#userid#&corpid=#corpid#)"}`.
senior_mode	Boolean	No	false	Whether to enable executive mode. Default: false. - true: Enable. Notes - Once enabled, the phone number is hidden from all Employees. - Regular Employees cannot send DINGs to or initiate DingTalk business calls with this user. - Executives can send DINGs to and initiate DingTalk business calls with each other. - false: Disable.
hired_date	Number	No	1597573616828	The hire date. Unix timestamp, in milliseconds.
manager_userid	String	No	001	The user ID of the direct manager.

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=YOUR_ACCESS_TOKEN' \
  -d 'outer_exclusive_corpid=ding12345' \
  -d 'outer_exclusive_userid=user01' \
  -d 'name=Zhang San' \
  -d 'dept_id_list=2,3,4' \
  -d 'userid=zhangsan' \
  -d 'telephone=010-86123456-2345' \
  -d 'job_number=4' \
  -d 'title=Technical Director' \
  -d 'email=test@xxx.com' \
  -d 'work_place=Future Park' \
  -d 'remark=Alias information'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/create");
OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
req.setUserid("zhangsan");
req.setName("Zhang San");
req.setMobile("13800138000");
req.setHideMobile(false);
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("Remarks");
req.setDeptIdList("2,3,4");
List<DeptOrder> list2 = new ArrayList<DeptOrder>();
DeptOrder obj3 = new DeptOrder();
list2.add(obj3);
req.setDeptOrderList(list2);
List<DeptTitle> list5 = new ArrayList<DeptTitle>();
DeptTitle obj6 = new DeptTitle();
list5.add(obj6);
req.setDeptTitleList(list5);
req.setSeniorMode(false);
req.setHiredDate(1597573616828L);
req.setLoginEmail("test@xxx.com");
req.setExclusiveAccount(false);
req.setExclusiveAccountType("dingtalk");
req.setLoginId("login_id3");
req.setInitPassword("init_password220");
List<DeptPosition> list8 = new ArrayList<DeptPosition>();
DeptPosition obj9 = new DeptPosition();
list8.add(obj9);
req.setDeptPositionList(list8);
req.setOrgEmailType("profession");
req.setManagerUserid("001");
req.setExclusiveMobile("+86-13412341234");
req.setExclusiveMobileVerifyStatus("verified/notVerified");
req.setOuterExclusiveCorpid("corpid");
req.setOuterExclusiveUserid("userid");
req.setAvatarMediaId("@lALPDfmVUw19YdrNA-jNA-g");
req.setNickname("Name");
req.setExtAttrsUpdateMode(0L);
List<EmpExtAttr> list11 = new ArrayList<EmpExtAttr>();
EmpExtAttr obj12 = new EmpExtAttr();
list11.add(obj12);
req.setExtAttrs(list11);
req.setGender("F/M/none");
req.setLimited(false);
req.setHasSubordinate(false);
req.setDeptName("Department1-Department11-Department111");
req.setFlowerName("Alias");
req.setSendPasswordToUser(false);
req.setCheckUserProtect(true);
OapiV2UserCreateResponse rsp = client.execute(req, "");
System.out.println(rsp.getBody());

Python

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

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

req.userid="zhangsan"
req.name="Zhang San"
req.mobile="13800138000"
req.hide_mobile=false
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="Remarks"
req.dept_id_list="2,3,4"
req.dept_order_list="[2,1]"
req.dept_title_list="[2,"Senior Product Manager"]"
req.senior_mode=false
req.hired_date=1597573616828
req.login_email="test@xxx.com"
req.exclusive_account=false
req.exclusive_account_type="dingtalk"
req.login_id="login_id3"
req.init_password="init_password220"
req.dept_position_list="[true,"Future Park","Senior Product Manager",2,"100"]"
req.org_email_type="profession"
req.manager_userid="001"
req.exclusive_mobile="+86-13412341234"
req.exclusive_mobile_verify_status="verified/notVerified"
req.outer_exclusive_corpid="corpid"
req.outer_exclusive_userid="userid"
req.avatarMediaId="@lALPDfmVUw19YdrNA-jNA-g"
req.nickname="Name"
req.ext_attrs_update_mode=0
req.ext_attrs="["emp:xxx",{"images":["https://img.alicdn.com/imgextra/i2/O1CN01IVwD5w1mqnRxmUBng_!!6000000005006-2-tps-64-64.png"],"text":"Click to visit the DingTalk official website","url":"www.dingtalk.io"}]"
req.gender="F/M/none"
req.limited=false
req.has_subordinate=false
req.dept_name="Department1-Department11-Department111"
req.flower_name="Alias"
req.send_password_to_user=false
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("Zhang San");
$req->setMobile("13800138000");
$req->setHideMobile("false");
$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("Remarks");
$req->setDeptIdList("2,3,4");
$dept_order_list = new DeptOrder;
$req->setDeptOrderList(array($dept_order_list));
$dept_title_list = new DeptTitle;
$req->setDeptTitleList(array($dept_title_list));
$req->setSeniorMode("false");
$req->setHiredDate("1597573616828");
$req->setLoginEmail("test@xxx.com");
$req->setExclusiveAccount("false");
$req->setExclusiveAccountType("dingtalk");
$req->setLoginId("login_id3");
$req->setInitPassword("init_password220");
$dept_position_list = new DeptPosition;
$req->setDeptPositionList(array($dept_position_list));
$req->setOrgEmailType("profession");
$req->setManagerUserid("001");
$req->setExclusiveMobile("+86-13412341234");
$req->setExclusiveMobileVerifyStatus("verified/notVerified");
$req->setOuterExclusiveCorpid("corpid");
$req->setOuterExclusiveUserid("userid");
$req->setAvatarMediaId("@lALPDfmVUw19YdrNA-jNA-g");
$req->setNickname("Name");
$req->setExtAttrsUpdateMode("0");
$ext_attrs = new EmpExtAttr;
$req->setExtAttrs(array($ext_attrs));
$req->setGender("F/M/none");
$req->setLimited("false");
$req->setHasSubordinate("false");
$req->setDeptName("Department1-Department11-Department111");
$req->setFlowerName("Alias");
$req->setSendPasswordToUser("false");
$req->setCheckUserProtect("true");
$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.OuterExclusiveCorpid = "ding12345"; 
req.OuterExclusiveUserid = "user01";  
req.Name = "Zhang San"; 
req.DeptIdList = "2,3,4"; 
req.Userid = "zhangsan"; 
req.Telephone = "010-86123456-2345";
req.JobNumber = "4"; 
req.Title = "Technical Director";  
req.Email = "test@xxx.com";  
req.OrgEmail = "test@xxx.com"; 
req.OrgEmailType = "profession";
req.WorkPlace = "Future Park"; 
req.Remark = "Alias information"; 
List<OapiV2UserCreateRequest.DeptOrderDomain> deptOrderList = new List<OapiV2UserCreateRequest.DeptOrderDomain>();
OapiV2UserCreateRequest.DeptOrderDomain orderObj = new OapiV2UserCreateRequest.DeptOrderDomain();
orderObj.DeptId = 2L;
orderObj.Order = 1L;
deptOrderList.Add(orderObj);
req.DeptOrderList_ = deptOrderList;
List<OapiV2UserCreateRequest.DeptTitleDomain> deptTitleList = new List<OapiV2UserCreateRequest.DeptTitleDomain>();
OapiV2UserCreateRequest.DeptTitleDomain titleObj = new OapiV2UserCreateRequest.DeptTitleDomain();
titleObj.DeptId = 2L;
titleObj.Title = "Senior Product Manager";
deptTitleList.Add(titleObj);
req.DeptTitleList_ = deptTitleList;
req.Extension = "{\"hobby\":\"travel\",\"age\":\"24\"}"; 
req.SeniorMode = false;  
req.HiredDate = 1597573616828L;    
req.ManagerUserid = "001";             
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 user ID of the Employee.
unionId	String	xxxx	The unionId 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 to find a solution based on the error message.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

Invite an Enterprise Account from another organization

API call description

Request

Query parameters

Request body

Request example

Response

Response body

Response body example

Error codes

​API call description

​Request

​Query parameters

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes

API call description

Request

Query parameters

Request body

Request example

Response

Response body

Response body example

Error codes