Get Department List

This interface is used to obtain the department list information under the current company.

Request Method

GET /departments

Request Parameters

None

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
departments	Array	See details below
Structure of departments

Parameter Name	Type	Description
id	Integer	Department ID
name	String	Department name
sub_department	Array	Sub-departments

Example

Request

curl https://demo.udesk.cn/open_api_v1/departments?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X GET \
-H 'content-type: application/json'

Response

{
    "code": 1000,
    "departments": [
        {
            "id": 1,
            "name": "Department 1",
            "sub_department": [
                {
                    "id": 10,
                    "name": "Sub-department 1",
                    "sub_department": [ {"id": 11, "name": "Sub-department 2", "sub_department": []} ]
                },
                {
                    "id": 11,
                    "name": "Sub-department 2",
                    "sub_department": []
                }
            ]
        },
        {
            "id": 2,
            "name": "Department 2",
            "sub_department": []
        },
        {
            "id": 3,
            "name": "Department 3",
            "sub_department": []
        }
    ]
}

Create Department

This interface is used to create a department.

Request Method

POST /departments

Request Parameters (request body)

Parameter	Required	Type	Description	Restrictions	Default
name	Yes	String	Department name	No more than 255 characters
parent_id	No	Integer	Parent department ID		0
Note: parent_id is the ID of the parent department. If not entered, the default is 0. When parent_id is 0, it means the parent department does not exist.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
id	Integer	ID of the department created successfully

Example

Request

curl https://demo.udesk.cn/open_api_v1/departments?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: application/json' \
-d '
{
  "name": "Department 12",
  "parent_id": 1
}'

Response

{
    "code": 1000,
    "id": 5
}

Edit Department

This interface is used to edit the basic information of an existing department.

Request Method

PUT /departments/:id

Request Parameters (url)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Department ID

Request Parameters (request body)

Parameter	Required	Type	Description	Restrictions	Default
name	Yes	String	Department name	No more than 255 characters
Note: This interface can only modify the name of the department based on the id, and cannot modify the parent_id of the department, that is, it cannot change the hierarchical relationship of the department. Even if parent_id is added in the request parameters, it will not take effect and there will be no error message.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
department	Object	Department information, structure as follows

Structure of department

Parameter Name	Type	Description
id	Integer	Department ID
name	String	Department name
parent_id	Integer	Parent department ID

Example

Request

curl https://demo.udesk.cn/open_api_v1/departments/5?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: application/json' \
-d '{"name": "New Department 12"}'

Response

{
    "code": 1000,
    "department": {
      "id": 5,
      "name": "New Department 12",
      "parent_id": 1
    }
}

Delete Department

This interface is used to delete an existing department.

Request Method

DELETE /departments/:id

Request Parameters (url)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Department ID

Request Parameters (request body)

None

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Execution result explanation

Example

Request

curl https://demo.udesk.cn/open_api_v1/departments/5?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE \
-H 'content-type: application/json'

Response

{
    "code": 1000,
    "message": "Department with ID 5 deleted successfully"
}

---

Error Code Description

Error Code	Message Information	Exception:message Information	Description
2000	Unknown error	Verification failed: Name already in use	The name has already been used
		Non-existent parent department with parent_id xxx	The parent department with the provided parent_id xxx does not exist
		The provided parent_id is not a non-negative integer	The format of the provided parent_id is incorrect; it is not a non-negative integer
		The resource was not found	The department to be edited was not found based on the provided id; it may not exist or the id format is incorrect
2015	Non-administrators cannot operate	Non-administrators cannot operate	The email address used to call the interface must be an administrator's email; non-administrators cannot perform operations
2059	Open API signature is incorrect	Open API signature is incorrect	The Open API signature is incorrect. For details, refer to the documentation in the Authentication section