读取获授权成员的基础资料

按一个已知 userId 查询成员基础信息，为业务系统关联身份。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

开通 qyapi_get_member；应用通讯录范围包含目标成员。
查询手机号、邮箱需额外权限，本例只消费基础字段。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

DINGTALK_ACCESS_TOKEN: 应用级令牌；取下面 token 操作返回的 access_token，不是 Webhook access_token。

export DINGTALK_ACCESS_TOKEN='replace_with_app_access_token'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
按机器人单聊场景取得组织应用 Token。
02
在企业后台或已经授权的部门用户列表取得 userId，不把 unionId 当成 userId。
03
替换 body.userid，提交 form 请求，读取 result 中所需字段；不存在的敏感字段保持空缺。

调用 01

读取单个用户详情

旧版 OAPI 用户接口仍提供服务；请求按官方 form 示例发送，保留成员信息读权限。

POSThttps://oapi.dingtalk.com/topapi/v2/user/get?access_token=${DINGTALK_ACCESS_TOKEN}

请求头

Content-Type: application/x-www-form-urlencoded

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`access_token`Query	string必填	目标组织的应用令牌。
`userid`请求体	string必填	本组织 userId，不是 unionId。
`language`请求体	string可选	zh_CN（默认）或 en_US。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${DINGTALK_ACCESS_TOKEN}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'userid=replace_with_userid' \
  --data-urlencode 'language=zh_CN'

import json
import os
import re
import urllib.request
import urllib.error
import urllib.parse

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${DINGTALK_ACCESS_TOKEN}")
headers = {
    "Content-Type": expand("application/x-www-form-urlencoded"),
}
body = {
    "userid": "replace_with_userid",
    "language": "zh_CN",
}
data = urllib.parse.urlencode(body).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${DINGTALK_ACCESS_TOKEN}");
const headers = Object.fromEntries(
  Object.entries({
  "Content-Type": "application/x-www-form-urlencoded"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "userid": "replace_with_userid",
  "language": "zh_CN"
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: new URLSearchParams(body).toString(),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。读取 result.userid、name、dept_id_list；敏感字段可能缺失。以下为结构示意，非本站实测结果。

{
  "errcode": 0,
  "errmsg": "ok",
  "result": {
    "userid": "example_user",
    "name": "测试成员",
    "dept_id_list": [
      1
    ],
    "active": true
  }
}

常见错误与排查

33012无效 userId: 确认用户属于 Token 的组织并在应用授权范围内。
400002参数不合法: 核对 userid 和 language 格式。

调用注意

需要 qyapi_get_member 成员信息读权限；手机号/邮箱另需字段权限，本文不申请敏感字段。
单用户查询没有分页；对大量成员应先按部门列表接口分页获取 userId，再按需查询。

查询用户详情

注意事项

该接口不读取其他企业的员工资料；Token 的组织上下文决定资源范围。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
获取应用的 Access Token核验日期 2026-10-15
02
查询用户详情核验日期 2026-10-15

钉钉开放平台的其他调用手册

向群发送自定义机器人通知获取应用令牌并发送机器人单聊

← 返回钉钉开放平台的全部功能