> ## Documentation Index > Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a user > Call this API to create a new user, covering request parameters, the response structure, and the extension parameter. 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: * [Create an SSO Enterprise Account](/open/development/create-an-sso-account) * [Create a DingTalk-built Enterprise Account](/open/development/create-dingtalk-user-created-dedicated-account) * [Invite Enterprise Accounts from other organizations to join](/open/development/invite-other-organization-specific-accounts-to-join) ## Request | **Basic information** | | | --------------------- | ---------------------------------------------------------------------------------------------- | | HTTP URL | [https://api.dingtalk.io/topapi/v2/user/create](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](/open/development/obtain-orgapp-token). | ### 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](https://oa.dingtalk.io) 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](mailto: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](mailto: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](https://oa.dingtalk.io/index_new.htm#/setting/contactInfo) > 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](mailto: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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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' ``` Java ```java theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 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 deptOrderList = new ArrayList(); 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 ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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) ``` PHP ```php theme={"theme":{"light":"github-light","dark":"github-dark"}} 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"); ``` C# ```csharp theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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](/open/development/server-api-error-codes-1) 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. 1. Sign in to the [DingTalk Admin Console](https://login.dingtalk.io/). 2. Click Internal Contacts Settings, then click **Member Field Management** > **Add Custom Field**.