跳到主要内容

查询企业员工信息列表

1. 接口描述

接口请求域名: ess.tencentcloudapi.com 。

此接口(DescribeIntegrationEmployees)用于分页查询企业员工信息列表,支持设置过滤条件以筛选员工查询结果。

默认接口请求频率限制:20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称必选类型描述
ActionString公共参数,本接口取值:DescribeIntegrationEmployees。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
OperatorUserInfo执行本接口操作的员工信息。使用此接口时,必须填写UserId。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
LimitInteger指定分页每页返回的数据条数,单页最大支持 20。
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
Filters.NArray of Filter查询的关键字段,支持Key-Values查询。可选键值如下:

  • Key:"Status",根据实名状态查询员工,Values可选:
    • ["IsVerified"]:查询已实名的员工
    • ["NotVerified"]:查询未实名的员工

  • Key:"DepartmentId",根据部门ID查询部门下的员工,Values为指定的部门ID:["DepartmentId"]

  • Key:"UserId",根据用户ID查询员工,Values为指定的用户ID:["UserId"]

  • Key:"UserWeWorkOpenId",根据用户企微账号ID查询员工,Values为指定用户的企微账号ID:["UserWeWorkOpenId"]

  • Key:"StaffOpenId",根据第三方系统用户OpenId查询员工,Values为第三方系统用户OpenId列表:["OpenId1","OpenId2",...]

  • Key:"RoleId",根据电子签角色ID查询员工,Values为指定的角色ID,满足其中任意一个角色即可:["RoleId1","RoleId2",...]

OffsetInteger指定分页返回第几页的数据,如果不传默认返回第一页。页码从 0 开始,即首页为 0,最大20000。

3. 输出参数

参数名称类型描述
EmployeesArray of Staff员工信息列表。
注意:此字段可能返回 null,表示取不到有效值。
OffsetInteger指定分页返回第几页的数据。页码从 0 开始,即首页为 0,最大20000。
注意:此字段可能返回 null,表示取不到有效值。
示例值:0
LimitInteger指定分页每页返回的数据条数,单页最大支持 20。
示例值:15
TotalCountInteger符合条件的员工数量。
示例值:10
RequestIdString唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 错误示例-参数不合法

在使用此接口时,需要按照入参描述进行相应的设置,以确保参数的合法性。如果参数设置不合法,此接口将返回错误信息。

  1. 将Limit参数设置为21,超过最大值20。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationEmployees
<公共请求参数>

{
"Operator": {
"UserId": "11234********************678901"
},
"Filters": [
{
"Key": "Status",
"Values": [
"IsVerified"
]
}
],
"Limit": 21,
"Offset": 0
}

输出示例

{
"Response": {
"Error": {
"Code": "InvalidParameter.ParamError",
"Message": "参数Limit不正确"
},
"RequestId": "3b506b8a-xxxx-xxxx-xxxx-xxxxx9eaaadd"
}
}

示例2 查询员工列表(查询指定ID的员工)

接口支持指定ID查询员工,此处以企微账号ID为例查询指定员工

  1. Filter参数Key设置为"UserWeWorkOpenId";
  2. Filter参数Values设置为具体的企微账号ID;
  3. 设置Limit和Offset参数,从首页开始,每页查询20条数据返回。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationEmployees
<公共请求参数>

{
"Operator": {
"UserId": "11234********************678901"
},
"Filters": [
{
"Key": "UserWeWorkOpenId",
"Values": [
"axxxxxxxa"
]
}
],
"Limit": 20,
"Offset": 0
}

输出示例

{
"Response": {
"Employees": [
{
"CreatedOn": 1658114069,
"Department": {
"DepartmentId": "dp**********************155f2",
"DepartmentName": "**企业"
},
"DisplayName": "**",
"Email": "",
"Mobile": "123****4567",
"OpenId": "",
"QuiteJob": 0,
"ReceiveOpenId": "",
"ReceiveUserId": "",
"Roles": [
{
"RoleId": "ea4ab3******************a6902",
"RoleName": "法人"
},
{
"RoleId": "4fcbf3******************ea6c63",
"RoleName": "超级管理员"
},
{
"RoleId": "9b7d******************cf8e9",
"RoleName": "业务员"
},
{
"RoleId": "4dff1******************10b",
"RoleName": "企业员工"
}
],
"UserId": "yDRt******************BKpnZs",
"Verified": true,
"VerifiedOn": 1658114065,
"WeworkOpenId": "axxxxxxxa"
}
],
"Limit": 20,
"Offset": 0,
"RequestId": "s1663******************195",
"TotalCount": 1
}
}

示例3 查询员工列表(查询已实名员工列表)

查询已实名员工列表

  1. Filter参数Key设置为"Status";
  2. Filter参数Values设置为"IsVerified",表示查询已实名员工;
  3. 设置Limit和Offset参数,从首页开始,每页查询20条数据返回。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationEmployees
<公共请求参数>

{
"Operator": {
"UserId": "11234********************678901"
},
"Filters": [
{
"Key": "Status",
"Values": [
"IsVerified"
]
}
],
"Limit": 20,
"Offset": 0
}

输出示例

{
"Response": {
"Employees": [
{
"CreatedOn": 1658114069,
"Department": {
"DepartmentId": "dp**********************155f2",
"DepartmentName": "测试企业"
},
"DisplayName": "张三",
"Email": "",
"Mobile": "13300001233",
"OpenId": "",
"QuiteJob": 0,
"ReceiveOpenId": "",
"ReceiveUserId": "",
"Roles": [
{
"RoleId": "ea4ab3******************a6902",
"RoleName": "法人"
},
{
"RoleId": "9b7d******************cf8e9",
"RoleName": "业务员"
},
{
"RoleId": "4dff1******************10b",
"RoleName": "企业员工"
}
],
"UserId": "yDRt******************BKpnZs",
"Verified": true,
"VerifiedOn": 1658114065,
"WeworkOpenId": ""
},
{
"CreatedOn": 1658114000,
"Department": {
"DepartmentId": "dp**********************155f2",
"DepartmentName": "测试企业"
},
"DisplayName": "李四",
"Email": "",
"Mobile": "13500001234",
"OpenId": "",
"QuiteJob": 0,
"ReceiveOpenId": "",
"ReceiveUserId": "",
"Roles": [
{
"RoleId": "4fcbf3******************ea6c63",
"RoleName": "超级管理员"
}
],
"UserId": "yDwJ******************BGQyov",
"Verified": true,
"VerifiedOn": 1658114066,
"WeworkOpenId": ""
}
],
"Limit": 20,
"Offset": 0,
"RequestId": "s1663******************195",
"TotalCount": 2
}
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码描述
FailedOperation操作失败。
InternalError.System系统错误,请稍后重试。
InvalidParameter.InvalidChannelChannel不正确。
InvalidParameter.InvalidLimit参数Limit不正确。
InvalidParameter.InvalidOffset参数Offset不正确。
InvalidParameter.InvalidOperatorId操作人ID不正确。
InvalidParameter.InvalidOrganizationId机构ID不正确。
InvalidParameter.ParamError参数错误。
InvalidParameterValue.Mask需要屏蔽的告警。
OperationDenied操作被拒绝。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoIdentityVerify未通过个人实名认证。
OperationDenied.NoLogin用户未登录,请先登录后再操作。
OperationDenied.SubOrgNotJoin子企业暂未加入。
ResourceUnavailable资源不可用。
UnauthorizedOperation未授权操作。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062