> ## 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 department > Call this API to create a new department in the enterprise Contacts, specifying the parent department and department details in the request and receiving the new department ID in the response. Call this API to create a new department. ## Request | **Basic information** | | | --------------------- | ---------------------------------------------------------------------------------------------------------- | | HTTP URL | [https://api.dingtalk.io/topapi/v2/department/create](https://api.dingtalk.io/topapi/v2/department/create) | | HTTP Method | POST | | Supported app type | appType-Internal app | | Required permission | permission-qyapi\_manage\_addresslist-Contacts data management permission | ### Query parameter | Name | Type | Required | Example | Description | | ------------- | ------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_token | String | Yes | bE74xxxx | The app credential used to call this API. Obtain it through the API for getting the [access\_token of an internal app](/open/development/obtain-orgapp-token). | ### Request body | Name | Type | Required | Example | Description | | ----------------------- | ------- | -------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | String | Yes | Development Department | The department name. The length must be 1 to 64 characters. The characters "-" and "," are not allowed. | | parent\_id | Number | Yes | 10 | The parent department ID. The root department ID is 1. | | hide\_dept | Boolean | No | true | Whether to hide this department: - **true**: Hide the department. After hiding, this department is not displayed in the company contacts. - **false (Default)**: Display the department. | | dept\_permits | String | No | "123,456" | The list of other departments that are allowed to view this department. The total number cannot exceed 50. This value takes effect when **hide\_dept** is set to **true**. | | user\_permits | String | No | "user123,manager222" | The list of userIds of users that are allowed to view this department. The total number cannot exceed 50. This value takes effect when **hide\_dept** is set to **true**. | | outer\_dept | Boolean | No | true | Whether to restrict members of this department from viewing the contacts: - **true**: Enable the restriction. After enabling, members of this department can only see contacts within the specified scope. - **false (Default)**: No restriction. | | outer\_dept\_only\_self | Boolean | No | false | Whether members of this department can only view the contacts of their own department and subordinate departments: - **true**: Can only view the contacts of their own department and subordinate departments. - **false**: Cannot view any contacts, and can only see themselves in the contacts. This parameter takes effect when **outer\_dept** is set to **true**. | | outer\_permit\_users | String | No | "manager123,user123" | The list of userIds of contact users that members of this department are allowed to view. The total number cannot exceed 50. This parameter takes effect when **outer\_dept** is set to **true**. | | outer\_permit\_depts | String | No | "456,123" | The list of contact department IDs that members of this department are allowed to view. The total number cannot exceed 50. This parameter takes effect when **outer\_dept** is set to **true**. | | create\_dept\_group | Boolean | No | true | Whether to create an enterprise group associated with this department. The default value is **false**, meaning no group is created. | | auto\_approve\_apply | Boolean | No | false | Whether to accept requests to join this department by default: - **true:** Requests to join this department are accepted by default. - **false:** Requests to join this department must be approved by an admin with the required permissions. | | order | Number | No | 10 | The sort value within the parent department. A smaller order value places the department higher in the sort order. | | source\_identifier | String | No | HR Department | The department identifier field. Developers can use this field to uniquely identify a department and map it to a department in an external contact list outside DingTalk. | ### Request example ```curl theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.dingtalk.io/topapi/v2/department/create" \ -H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \ -d 'access_token=d5ca5xxxxa8' \ -d 'parent_id=10' \ -d 'outer_dept=true' \ -d 'hide_dept=true' \ -d 'create_dept_group=true' \ -d 'order=10' \ -d 'name=HR' \ -d 'source_identifier=HR%20Department' \ -d 'dept_permits=3%2C4%2C5' \ -d 'user_permits=100%2C200' \ -d 'outer_permit_users=500%2C600' \ -d 'outer_permit_depts=6%2C7%2C8' \ -d 'outer_dept_only_self=true' ``` Java ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/department/create"); OapiV2DepartmentCreateRequest req = new OapiV2DepartmentCreateRequest(); req.setParentId(10L); req.setOuterDept(true); req.setHideDept(true); req.setCreateDeptGroup(true); req.setOrder(10L); req.setName("HR"); req.setSourceIdentifier("HR Department"); req.setDeptPermits("3,4,5"); req.setUserPermits("100,200"); req.setOuterPermitUsers("500,600"); req.setOuterPermitDepts("6,7,8"); req.setOuterDeptOnlySelf(true); OapiV2DepartmentCreateResponse rsp = client.execute(req, access_token); System.out.println(rsp.getBody()); ``` Python ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # -*- coding: utf-8 -*- import dingtalk.api req=dingtalk.api.OapiV2DepartmentCreateRequest("https://api.dingtalk.io/topapi/v2/department/create") req.parent_id=10 req.outer_dept=true req.hide_dept=true req.create_dept_group=true req.order=10 req.name="HR" req.source_identifier="HR Department" req.dept_permits="3,4,5" req.user_permits="100,200" req.outer_permit_users="500,600" req.outer_permit_depts="6,7,8" req.outer_dept_only_self=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 OapiV2DepartmentCreateRequest; $req->setName("HR"); $req->setParentId("10"); $req->setHideDept("true"); $req->setDeptPermits("3,4,5"); $req->setUserPermits("100,200"); $req->setOuterPermitUsers("500,600"); $req->setOuterPermitDepts("6,7,8"); $req->setOuterDeptOnlySelf("true"); $req->setOuterDept("true"); $req->setCreateDeptGroup("true"); $req->setOrder("10"); $req->setSourceIdentifier("HR Department"); $resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/department/create"); ``` C# ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/department/create"); OapiV2DepartmentCreateRequest req = new OapiV2DepartmentCreateRequest(); req.ParentId = 10L; req.OuterDept = true; req.HideDept = true; req.CreateDeptGroup = true; req.Order = 10L; req.Name = "HR"; req.SourceIdentifier = "HR Department"; req.DeptPermits = "3,4,5"; req.UserPermits = "100,200"; req.OuterPermitUsers = "500,600"; req.OuterPermitDepts = "6,7,8"; req.OuterDeptOnlySelf = true; OapiV2DepartmentCreateResponse rsp = client.Execute(req, access_token); Console.WriteLine(rsp.Body); ``` ## Response ### Response body | Name | Type | Example | Description | | ----------- | ------------------ | ------------ | ----------------------------------- | | request\_id | String | 6iq4zcul5zjp | The request ID. | | errcode | Number | 0 | The return code. | | errmsg | String | ok | The description of the return code. | | result | DeptCreateResponse | | The call result. | | dept\_id | Number | 100 | The department ID. | ### Response body example ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "errcode": 0, "errmsg":"ok", "result": { "dept_id": 41xxxx76 }, "request_id": "6iq4zcul5zjp" } ``` ### Error codes If an error occurs when you call this API, look up the solution in the [Global error codes](/open/development/server-api-error-codes-1) document based on the error message. | Error code (errcode) | Error message (errmsg) | Solution | | -------------------- | -------------------------------- | ------------------------------------------------------------------------- | | 40035 | Invalid parameter | Make sure the parameters are filled in as required by the document above. | | 43007 | Authorization required | Make sure the access\_token has the permissions required for this action. | | 60004 | Parent department does not exist | Check whether parent\_id is correct. | | 600109 | Invalid visible ID list | Check whether the visible list meets the requirements. | | -1 | System busy | Try again later. |