获取部门成员列表

分页获取指定部门下的直属成员列表。

接口信息

项目	说明
接口名称	获取部门成员列表
权限标识	contact.department.read（读取组织架构）
请求方式	POST / GET
请求地址	https://{gateway_host}/open/v1/contact/user/list
数据格式	application/json（POST 时）或 URL Query
鉴权方式	应用级 access_token（需具备 contact.department.read 权限）

前置条件

1. 应用已在管理后台「内部应用」中发布并启用。
2. 已获取有效的应用级凭证 access_token。
3. 查询的部门必须处于应用的可见范围之内。

请求参数

请求头

请求头	必填	说明
Authorization	否	Bearer <access_token>，推荐的凭证传递方式（与 Query / 表单三选一）
Content-Type	否	POST 请求使用 JSON 时传 application/json

参数列表

参数支持在 POST JSON Body、POST Form 表单或 GET Query 中传递：

参数名	类型	必填	说明
access_token	string	是	应用级令牌（若未在 Authorization 头中携带，则必填）
dept_id	string	是	部门 ID（正整数字符串）。必填，不支持省略。若应用仅授权单根部门，可传 "1" 作为根部门映射。系统兼容别名 deptId、departmentId、department_id
cursor	string	否	分页游标，从 0 开始的数字偏移量，默认 0。系统兼容别名 next_cursor、nextCursor
size	integer	否	每页返回成员数量，取值范围 1–100，默认 100
language	string	否	语言/国际化预留参数，当前不影响返回内容

请求示例

POST 请求示例：

POST https://{gateway_host}/open/v1/contact/user/list
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "dept_id": "20",
  "cursor": "0",
  "size": 50
}

GET 请求示例：

GET https://{gateway_host}/open/v1/contact/user/list?dept_id=20&cursor=0&size=50
Authorization: Bearer <access_token>

响应参数

成功响应（平台统一响应外壳）：

{
  "code": 200,
  "msg": "",
  "data": {
    "users": [
      {
        "userId": "42",
        "name": "张三",
        "avatar": "https://cdn.example.com/avatar/42.png",
        "mobile": "13800000000",
        "email": "zhangsan@example.com",
        "jobNumber": "A-001",
        "title": "工程师",
        "deptIdList": ["10", "20"]
      }
    ],
    "hasMore": true,
    "nextCursor": "1"
  }
}

字段	类型	说明
code	integer	业务状态码，200 表示成功
msg	string	提示信息，成功时为空
data.users	object[]	成员列表，无成员时为 []。字段定义与《获取成员详情》接口一致
data.users[].userId	string	成员 ID
data.users[].name	string	成员昵称 / 姓名
data.users[].avatar	string	头像地址，未设置时不返回
data.users[].mobile	string	手机号，未设置时不返回
data.users[].email	string	邮箱地址，未设置时不返回
data.users[].jobNumber	string	员工工号，未设置时不返回
data.users[].title	string	职位，未设置时不返回
data.users[].deptIdList	string[]	成员所属部门 ID 列表（仅包含可见部门）
data.hasMore	boolean	是否还有更多成员数据
data.nextCursor	string	下一页分页游标。仅在 hasMore 为 true 时返回，后续请求作为 cursor 传入

返回规则与注意事项

1. 直属成员与不递归：本接口仅返回直接隶属于该部门的成员，不会递归展开子部门成员。若需要获取子部门成员，应先通过《获取部门列表》获取子部门 ID，再逐个部门调用本接口。
2. 完整字段与免二次查询：返回的成员对象包含了成员的全部公开字段（与《获取成员详情》一致），因此在遍历组织架构时无需重复针对每个成员单独调用详情接口。
3. 可见范围过滤：只有状态正常且落在应用可见范围内的成员才会返回。如果某成员直属于该部门，但未被授权给当前应用，则不会出现在列表中。
4. 分页终止判断：请严格根据 hasMore 和 nextCursor 判断分页是否结束，不要依赖当前页条数是否小于 size。

错误码说明

鉴权与中间件错误（HTTP 状态码）

HTTP 状态码	msg 错误码	说明
401	INVALID_TOKEN	令牌缺失、已过期、已失效，或应用不可用
403	SCOPE_DENIED	令牌缺少 contact.department.read 权限
403	IP_DENIED	请求来源 IP 未命中应用安全设置的 IP 白名单

业务错误（HTTP 200，code=500）

{
  "code": 500,
  "msg": "DEPARTMENT_NOT_FOUND",
  "data": null
}

msg 错误码	说明与排查建议
INVALID_REQUEST	参数 dept_id 缺失、为空或不是合法正整数；cursor 格式错误；size 超出 1–100 范围
DEPARTMENT_NOT_FOUND	部门不存在、已被删除，或该部门不在应用可见范围内
PERMISSION_DENIED	应用状态异常（已被停用、取消发布或删除）
SERVER_ERROR	服务端内部异常，请稍后重试

多语言调用示例

以下示例使用服务端调用方式；应用密钥和应用令牌不得下发到客户端。

Shell

curl -sS -X POST "https://{gateway_host}/open/v1/contact/user/list" \
  -H "Authorization: Bearer access-token-xxx" \\\n  -H "Content-Type: application/json" \
  -d '{"dept_id":"20","cursor":"0","size":50}'

PHP

<?php
// 中文注释：生产环境应检查 HTTP 状态码和响应体，再映射业务错误。
$handle = curl_init('https://{gateway_host}/open/v1/contact/user/list');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer access-token-xxx', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"dept_id":"20","cursor":"0","size":50}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($handle);
curl_close($handle);

Golang

package main

import (
    "bytes"
    "net/http"
)

func main() {
    // 中文注释：令牌只在服务端请求中使用，并按接口约定携带。
    request, _ := http.NewRequest(http.MethodPost, "https://{gateway_host}/open/v1/contact/user/list", bytes.NewBufferString(`{"dept_id":"20","cursor":"0","size":50}`))
    request.Header.Set("Authorization", "Bearer access-token-xxx")
    request.Header.Set("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
}

C++

#include <curl/curl.h>

int main() {
    // 中文注释：生产环境应启用 TLS 校验并处理 HTTP 错误。
    CURL* handle = curl_easy_init();
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "Authorization: Bearer access-token-xxx");
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(handle, CURLOPT_URL, "https://{gateway_host}/open/v1/contact/user/list");
    curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "POST");
    curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(handle, CURLOPT_POSTFIELDS, R"({"dept_id":"20","cursor":"0","size":50})");
    const CURLcode result = curl_easy_perform(handle);
    curl_slist_free_all(headers);
    curl_easy_cleanup(handle);
    return result == CURLE_OK ? 0 : 1;
}