Department

Department List

***/api/v1/department/list?token=***&id=1

Request Parameters

name	type	required	description
id	number	no	department id

Sample Response data:

{
  "errcode": 0,
  "errmsg": "ok",
  "departments": [
    {
      "id": 1,
      "name": "句子科技",
      "parentid": 0,
      "order": 0
    },
    {
      "id": 2,
      "name": "研发一部",
      "parentid": 1,
      "order": 99998000
    },
    {
      "id": 3,
      "name": "设计",
      "parentid": 1,
      "order": 99999000
    }
  ]
}

Description:

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message
departments	array	yes	department list
id	number	yes	department id
name	string	yes	department name
parentid	number	yes	parent department id, root department will be 1
order	number	yes	order within parent department, larger number is before smaller number

Department User List

GET ***/api/v1/department/simpleUser?token=***&departmentId=**

Description

name	type	required	description
departmentId	number	yes	department id

Sample Response data:

{
  "errcode": 0,
  "errmsg": "ok",
  "user_list": [
    {
      "userid": "JuXiaoMi",
      "name": "桔小秘",
      "department": [
        18
      ]
    },
    {
      "userid": "JuXiaoMi22",
      "name": "桔小秘22",
      "department": [
        18
      ]
    },
    {
      "userid": "AoSiLu",
      "name": "奥斯陆",
      "department": [
        18
      ]
    }
  ]
}

Description

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message
user_list	array	yes	department user list
user_list.userid	string	yes	corp user id
user_list.name	string	yes	corp user name
user_list.department	array	yes	departments that the corp user belong to

Create Department

POST ***/api/v1/department/create?token=***

Sample Request Data:

{
  "id": 21
  "name":"更新部门",
  "name_en": "update department",
  "parentid": 1
}

Description:

name	type	required	description
id	number	no	department id, if this is empty, the department id will be generated automatically
name	string	no	department name, can not be duplicate within same parent department
name_en	string	no	english name for the department
parentid	number	no	parent department id of the current department

Sample Response data:

{
  errcode: 0,
  errmsg: "created"
  id: 21
}

Description:

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message
id	number	yes	department id

Error Code

code	description
60008	department already exist
-1	failed to create the department

Update Department

POST ***/api/v1/department/update?token=***

Sample Request Data:

{
  "id": 21
  "name":"更新部门",
  "name_en": "update department",
  "parentid": 1
}

Description:

name	type	required	description
id	number	yes	department id
name	string	no	department name
name_en	string	no	department english name
parentid	number	no	parent department id

Sample Response data:

{
  errcode: 0,
  errmsg: "updated"
}

Description:

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message

WARNING

To update parentid, move department, you need to grant internal app 【句子助手】 with permission to the parent department.

Error Code

code	description
-2	failed to update the department

Delete Department

POST ***/api/v1/department/delete?token=***

Sample Request Data:

{
  "id": 38
}

Description:

name	type	required	description
id	number	yes	department id

Sample Response data:

{
  errcode: 0,
  errmsg: "deleted"
}

Description:

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message

WARNING

1. Can not delete root department
2. Can not delete department with child department or corp users

Batch Update Department Users

POST ***/api/v1/department/updateDeptUsers?token=***

Sample Request Data:

{
  "user_list":[
    {
      "userid":"juzikeji",
      "department":[12,41]
    },
    {
      "userid":"juzikeji123",
      "department":[21,39]
    }
	]
}

Description

name	type	required	description
user_list	array	yes	corp user list to be updated
user_list.userid	string	yes	corp user id
user_list.department	array	yes	department id list

Sample Response data:

{
  errcode: 0,
  errmsg: "created"
  fail_list: [
    {
      "userid":"juzikeji123",
      "department":[21,39],
      "errcode": 60006,
      "errmsg": "error message"
    }
  ]
}

Description:

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message
fail_list	array	yes	update failed list
fail_list.userid	string	yes	corp user id
fail_list.department	array	yes	department id list
fail_list.errcode	number	yes	error code from WeCom
fail_list.errmsg	string	yes	error message from WeCom

Batch Create/Update Department

POST ***/api/v1/department/batchCreate?token=***

Sample Request Data:

{
  "departments":[
    {
      "id": 21,
      "name": "测试部门批量测试",
      "parentid":13,
      "order": 111
    },
    {
      "id":13,
      "name":"测试父部门124",
      "parentid":1
    }
  ]
}

Description

name	type	required	description
departments	array	yes	departments to be updated
departments.id	number	yes	department id
departments.parentid	number	yes	parent department id
departments.name	string	yes	department name
departments.order	number	no	department order, empty or 0 will leave the order unchanged

Sample Response data:

{
  errcode: 0,
  errmsg: "ok"
  jobId: "1_1601381613_212170"
}

Description

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message
jobId	string	yes	async update department job id

WARNING

1. If a department is in the update list exists, will do update on the department
2. If a department is in the update list does not exist, will do insert
3. If a department is not in the update list, but in WeCom, and there is no child department or users in the department, will do delete

Error Code

code	description
-3	the job existed

Get Batch Department Update Result

POST ***/api/v1/department/getBatchResult?token=***&jobId=***

Sample Request Data:

***/api/v1/department/getBatchResult?token=***&jobId=1_1601381613_212170

Description

name	type	required	description
jobId	string	yes	the jobId returned from the batch update department

Sample Response data:

{
  "errcode": 0,
  "errmsg": "ok",
  "type": "replace_party",
  "result": [
    {
      "action": 2,
      "errcode": 0,
      "errmsg": "ok",
      "partyid": 21
    }
  ],
  "total": 2,
  "percentage": 100,
  "status": 3
}

Description

name	type	required	description
errcode	number	yes	return code
errmsg	string	yes	error message
id	number	yes	department id