企業(yè)號通訊錄具備完全開放的接口，你的應(yīng)用可以調(diào)用這些接口管理部門、成員和標簽。

你的應(yīng)用也可以使用部門、成員、標簽發(fā)消息，或更改應(yīng)用的可見范圍。

注意，每個部門的直屬員工上限為1000個；出于安全考慮，某些接口需要在管理端有明確的授權(quán)。

一、管理部門

1、創(chuàng)建部門

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN

請求包結(jié)構(gòu)體為:

{ 
   "name": "郵箱產(chǎn)品組", 
   "parentid": "1" 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
name	是	部門名稱。長度限制為1~64個字符
parentid	是	父親部門id。根部門id為1

• 權(quán)限說明

管理員須擁有“操作通訊錄”的接口權(quán)限，以及父部門的管理權(quán)限。

• 返回結(jié)果

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

參數(shù)	說明
errcode	返回碼
errmsg	對返回碼的文本描述內(nèi)容
id	創(chuàng)建的部門id。

2、更新部門

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/update?access_token=ACCESS_TOKEN

請求包結(jié)構(gòu)體為（如果非必須的字段未指定，則不更新該字段之前的設(shè)置值）:

{ 
   "id": 2, 
   "name": "郵箱產(chǎn)品部" 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
id	是	部門id。
name	否	更新的部門名稱。長度限制為0~64個字符。修改部門名稱時指定該參數(shù)

• 權(quán)限說明

管理員須擁有“操作通訊錄”的接口權(quán)限，以及該部門的管理權(quán)限。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "updated" 
  } 

3、刪除部門

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&id=1&id=2

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
id	是	部門id。（注：不能刪除根部門；不能刪除含有子部門、成員的部門）

• 權(quán)限說明

管理員須擁有“操作通訊錄”的接口權(quán)限，以及該部門的管理權(quán)限。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "deleted" 
  } 

4、獲取部門列表

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證

• 權(quán)限說明

管理員須擁有’獲取部門列表’的接口權(quán)限，以及對部門的查看權(quán)限。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "ok", 
     "department": [ 
         { 
             "id": 1, 
             "name": "廣州研發(fā)中心", 
             "parentid": 0 
         }, 
         { 
             "id": 2 
             "name": "郵箱產(chǎn)品部", 
             "parentid": 1 
         } 
     ] 
  } 

參數(shù)	說明
errcode	返回碼
errmsg	對返回碼的文本描述內(nèi)容
department	部門列表數(shù)據(jù)
id	部門id
name	部門名稱
parentid	父親部門id。根部門為1

二、管理成員

1、創(chuàng)建成員

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/create?access_token=ACCESS_TOKEN

請求包結(jié)構(gòu)體為:

{ 
   "userid": "zhangsan", 
   "name": "張三", 
   "department": [1, 2], 
   "position": "產(chǎn)品經(jīng)理", 
   "mobile": "15913215421", 
   "gender": 1, 
   "tel": "62394", 
   "email": "zhangsan@gzdev.com", 
   "weixinid": "zhangsan4dev" 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
userid	是	員工UserID。對應(yīng)管理端的帳號，企業(yè)內(nèi)必須唯一
name	是	成員名稱。長度為1~64個字符
department	否	成員所屬部門id列表。注意，每個部門的直屬員工上限為1000個
position	否	職位信息。長度為0~64個字符
mobile	否	手機號碼。企業(yè)內(nèi)必須唯一，mobile/weixinid/email三者不能同時為空
gender	否	性別。gender=0表示男，=1表示女。默認gender=0
tel	否	辦公電話。長度為0~64個字符
email	否	郵箱。長度為0~64個字符。企業(yè)內(nèi)必須唯一
weixinid	否	微信號。企業(yè)內(nèi)必須唯一

• 權(quán)限說明

管理員須擁有“操作通訊錄”的接口權(quán)限，以及指定部門的管理權(quán)限。

• 返回結(jié)果

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

2、更新成員

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/update?access_token=ACCESS_TOKEN

請求包示例如下（如果非必須的字段未指定，則不更新該字段之前的設(shè)置值）:

{ 
   "userid": "zhangsan", 
   "name": "李四", 
   "department": [1], 
   "position": "后臺工程師", 
   "mobile": "15913215421", 
   "gender": 1, 
   "tel": "62394", 
   "email": "zhangsan@gzdev.com", 
   "weixinid": "lisifordev", 
   "enable": 1 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
userid	是	員工UserID。對應(yīng)管理端的帳號，企業(yè)內(nèi)必須唯一
name	否	成員名稱。長度為0~64個字符
department	否	成員所屬部門id列表。注意，每個部門的直屬員工上限為1000個
position	否	職位信息。長度為0~64個字符
mobile	否	手機號碼。企業(yè)內(nèi)必須唯一，更新后的成員mobile/weixinid/email三者不能同時為空
gender	否	性別。gender=0表示男，=1表示女。默認gender=0
tel	否	辦公電話。長度為0~64個字符。必須企業(yè)內(nèi)唯一
email	否	郵箱。長度為0~64個字符。企業(yè)內(nèi)必須唯一
weixinid	否	微信號。企業(yè)內(nèi)必須唯一
enable	否	啟用/禁用成員。1表示啟用成員，0表示禁用成員

• 權(quán)限說明

管理員須擁有“操作通訊錄”的接口權(quán)限，以及指定部門、成員的管理權(quán)限。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "updated" 
  } 

3、刪除成員

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/delete?access_token=ACCESS_TOKEN&userid=lisi

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
userid	是	員工UserID。對應(yīng)管理端的帳號

• 權(quán)限說明

管理員須擁有“操作通訊錄”的接口權(quán)限，以及指定部門、成員的管理權(quán)限。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "deleted" 
  } 

4、獲取成員

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&userid=lisi

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
userid	是	員工UserID

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "ok", 
     "userid": "zhangsan", 
     "name": "李四", 
     "department": [1, 2], 
     "position": "后臺工程師", 
     "mobile": "15913215421", 
     "gender": 1, 
     "tel": "62394", 
     "email": "zhangsan@gzdev.com", 
     "weixinid": "lisifordev",   
     "avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0", 
     "status": 1 
  } 

參數(shù)	說明
errcode	返回碼
errmsg	對返回碼的文本描述內(nèi)容
userid	員工UserID
name	成員名稱
department	成員所屬部門id列表
position	職位信息
mobile	手機號碼
gender	性別。gender=0表示男，=1表示女
tel	辦公電話
email	郵箱
weixinid	微信號
avatar	頭像url。注：如果要獲取小圖將url最后的"/0"改成"/64"即可
status	關(guān)注狀態(tài): 1=已關(guān)注，2=已凍結(jié)，4=未關(guān)注

• 權(quán)限說明

管理員須擁有’獲取成員’的接口權(quán)限，以及成員的查看權(quán)限。

5、獲取部門成員

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=ACCESS_TOKEN&department_id=1&fetch_child=0&status=0

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
department_id	是	獲取的部門id
fetch_child	否	1/0：是否遞歸獲取子部門下面的成員
status	否	0獲取全部員工，1獲取已關(guān)注成員列表，2獲取禁用成員列表，4獲取未關(guān)注成員列表。status可疊加

• 權(quán)限說明

管理員須擁有’獲取部門成員’的接口權(quán)限，以及指定部門的查看權(quán)限。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "ok", 
     "userlist": [ 
             { 
                    "userid": "zhangsan", 
                    "name": "李四" 
             } 
       ] 
  } 

參數(shù)	說明
errcode	返回碼
errmsg	對返回碼的文本描述內(nèi)容
userlist	成員列表
userid	員工UserID
name	成員名稱

三、管理標簽

1、創(chuàng)建標簽

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/create?access_token=ACCESS_TOKEN

注：標簽鎖默認為未加鎖狀態(tài)

請求包結(jié)構(gòu)體為:

{ 
   "tagname": "UI" 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
tagname	是	標簽名稱。長度為1~64個字符，標簽不可與其他同組的標簽重名，也不可與全局標簽重名

• 權(quán)限說明

無限定。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "created" 
     "tagid": "1" 
  } 

2、更新標簽名字

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/update?access_token=ACCESS_TOKEN

請求包示例如下:

{ 
   "tagid": "1", 
   "tagname": "UI design" 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
tagid	是	標簽ID
tagname	是	標簽名稱。最長64個字符

• 權(quán)限說明

管理員必須是指定標簽的創(chuàng)建者。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "updated" 
  } 

3、刪除標簽

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/delete?access_token=ACCESS_TOKEN&tagid=1

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
tagid	是	標簽ID

• 權(quán)限說明

管理員必須是指定標簽的創(chuàng)建者，并且標簽的成員列表為空。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "deleted" 
  } 

4、獲取標簽成員

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/get?access_token=ACCESS_TOKEN&tagid=1

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
tagid	是	標簽ID

• 權(quán)限說明

管理員須擁有“獲取標簽成員”的接口權(quán)限，標簽須對管理員可見；返回列表僅包含管理員管轄范圍的成員。

• 返回結(jié)果

  { 
     "errcode": 0, 
     "errmsg": "ok", 
     "userlist": [ 
           { 
               "userid": "zhangsan", 
               "name": "李四" 
           } 
       ] 
  } 

參數(shù)	說明
errcode	錯誤碼
errmsg	錯誤消息
userlist	成員列表
userid	員工UserID

5、增加標簽成員

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/addtagusers?access_token=ACCESS_TOKEN

請求包示例如下:

{ 
   "tagid": "1", 
   "userlist":[ "user1","user2"] 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
tagid	是	標簽ID
userlist	是	企業(yè)員工ID列表

• 權(quán)限說明

標簽對管理員可見且未加鎖，成員屬于管理員管轄范圍。

• 返回結(jié)果

a)正確時返回

{ 
   "errcode": 0, 
   "errmsg": "ok" 
} 

b)若部分userid非法，則返回

{ 
   "errcode": 0, 
   "errmsg": "invalid userlist failed" 
   "invalidlist"："usr1|usr2|usr" 
} 

c)當(dāng)包含userid全部非法時返回

{ 
   "errcode": 40070, 
   "errmsg": "all list invalid " 
} 

參數(shù)	說明
errcode	錯誤碼
errmsg	錯誤消息
invalidlist	不在權(quán)限內(nèi)的員工ID列表，以“|”分隔

6、刪除標簽成員

• 請求說明

Https請求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/deltagusers?access_token=ACCESS_TOKEN

請求包如下

{ 
   "tagid": "1", 
   "userlist":[ "user1","user2"] 
} 

• 參數(shù)說明

參數(shù)	必須	說明
access_token	是	調(diào)用接口憑證
tagid	是	標簽ID
userlist	是	企業(yè)員工ID列表

• 權(quán)限說明

標簽對管理員可見且未加鎖，成員屬于管理員管轄范圍。

• 返回結(jié)果

a)正確時返回

{ 
   "errcode": 0, 
   "errmsg": "deleted" 
} 

b)若部分userid非法，則返回

{ 
   "errcode": 0, 
   "errmsg": "invalid userlist failed" 
   "invalidlist"："usr1|usr2|usr" 
} 

c)當(dāng)包含的userid全部非法時返回

{ 
   "errcode": 40031, 
   "errmsg": "all list invalid" 
} 

參數(shù)	說明
errcode	錯誤碼
errmsg	錯誤消息
invalidlist	不在權(quán)限內(nèi)的或者非法的員工ID列表，以“|”分隔