查询企业员工信息列表
1. 接口描述
接口请求域名： ess.tencentcloudapi.com 。
此接口（DescribeIntegrationEmployees）用于分页查询企业员工信息列表，支持设置过滤条件以筛选员工查询结果。
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：DescribeIntegrationEmployees。 |
| Version | 是 | String | 公共参数，本接口取值：2020-11-11。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| Operator | 是 | UserInfo | 执行本接口操作的员工信息。使用此接口时，必须填写UserId。 注: 在调用此接口时，请确保指定的员工已获得所需的接口调用权限，并具备接口传入的相应资源的数据权限。 |
| Limit | 是 | Integer | 指定分页每页返回的数据条数，单页最大支持 20。 |
| Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。 |
| Filters.N | 否 | Array of Filter | 查询的关键字段，支持Key-Values查询。可选键值如下：
|
| Offset | 否 | Integer | 指定分页返回第几页的数据，如果不传默认返回第一页。页码从 0 开始，即首页为 0，最大20000。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| Employees | Array of Staff | 员工信息列表。 注意：此字段可能返回 null，表示取不到有效值。 |
| Offset | Integer | 指定分页返回第几页的数据。页码从 0 开始，即首页为 0，最大20000。 注意：此字段可能返回 null，表示取不到有效值。 示例值：0 |
| Limit | Integer | 指定分页每页返回的数据条数，单页最大支持 20。 示例值：15 |
| TotalCount | Integer | 符合条件的员工数量。 示例值：10 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例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为例查询指定员工
- Filter参数Key设置为"UserWeWorkOpenId";
- Filter参数Values设置为具体的企微账号ID；
- 设置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 查询员工列表（查询已实名员工列表）
查询已实名员工列表
- Filter参数Key设置为"Status";
- Filter参数Values设置为"IsVerified"，表示查询已实名员工；
- 设置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.InvalidChannel | Channel不正确。 |
| 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 | 请升级到对应版本后即可使用该接口。 |