当前公开契约 · 联系人

企业微信查询用户详情 API

获取联系人详细资料。⚠️ 入参是 userIdList（数组），不是单个 userId —— 传单数会返回 userIdList is empty。响应也相应是列表，按传入顺序返回。同事取通讯录 vid（1688 前缀），外部联系人取 uin（7881 前缀）。

进入控制台试用查看完整契约

POST实例字段：appid更新：2026-10-11

请求地址

POST https://api.qingluanbot.com/qingluan/api/contact/getUserProfileDetail

请求示例

curl -X POST 'https://api.qingluanbot.com/qingluan/api/contact/getUserProfileDetail' \
  -H 'QL-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "appid": "we_xxxxxxxxxxxxxxx",
  "userId": 1000000000000001
}'

请求参数

字段	类型	要求	说明
`appid`	string	必填	青鸾实例 ID，形如 we_xxxxxxxxxxxxxxx。在开发者控制台「实例与回调」扫码上号后获得。
`userIdList`	array<integer>	可选	用户 ID 列表。必须是数组，传单个数字会返回 userIdList is empty。
`userId`	integer	可选	用户 ID。前缀决定类型：1688… 是本企业成员（取自「同步通讯录」的 vid），7881… 是外部联系人（取自「同步外部联系人」的 uin）。其他前缀会被直接拒绝。

响应判断

能力层接口返回包含 code、message、time 与 data 等字段；请以 code=0 判断业务成功。HTTP 200 只表示网关已返回响应，不能替代业务状态判断。

可能的响应状态

HTTP 状态	公开契约说明
`200`	原样返回（code = 0 即成功）
`403`	受控接口，需通过控制台配置
`404`	appid 不存在或无权访问

200 响应示例

{
  "code": 0,
  "data": {
    "info": {
      "alias": "示例别名",
      "attr": 146082112,
      "attr2": 777651084,
      "attr3": 0,
      "bindEmailStatus": 1,
      "birthday": "2000-09-01 12:00:00",
      "bizMail": "xiaoyi@taichuinfo.cn",
      "bizUin": 1,
      "businessDesc": {
        "fieldId": "YnVzaV9kZXNj",
        "fieldName": "5oiR55qE5Lia5Yqh",
        "fieldType": 4
      },
      "corpDesc": {
        "fieldId": "Y29ycF9kZXNj",
        "fieldName": "5LyB5Lia5LuL57uN",
        "fieldType": 4
      },
      "corpDescInfo": {
        "infoName": "5LyB5Lia5ZCN54mH",
        "jumpUrl": "d3h3b3JrOi8vanVtcD90YXJnZXQ9anVtcF90b190b29sJnRvb2xpZD0zMDAwMTAxMSZzY2VuZT0y",
        "profileUrl": "aHR0cHM6Ly93b3JrLndlaXhp…<已截断>"
      },
      "corpId": 1000000000000002,
      "customInfo": {},
      "dispOrder": 0,
      "emailAddr": "",
      "englishName": "XiaoYi-FuWuZhiChi",
      "externFinder": {
        "addTime": 1788245001,
        "finderId": "djJfMDYwMDAwMjMxMDAzYjIwZmFlYzhjYWUzOGUxZmMxZDdjZTAzZWUzY2IwNzdkOGQ4YzYzMTAwY2JlYjlkNzAxMDYwYWRhZGQ1YzE2NUBmaW5kZXI=",
        "finderIntId": 1,
        "image": "aHR0cHM6Ly93eC5xbG9nby5j…<已截断>",
        "nickName": "5oqA5pyv5pSv5oyB5bCP5paH",
        "status": 2
      },
      "externalCustomInfo": {},
      "gender": 1,
      "gid": 1000000000000004,
      "holidayInfo": {
        "createTime": 0,
        "holidayDesc": "",
        "holidayGenerateSrc": 0,
        "holidayIconIndex": 0,
        "holidayInfoId": 0,
        "holidayStatus": 0,
        "holidayStatusNew": 0,
        "oldHolidayIconIndex": 0,
        "vacationSyncType": 0
      },
      "iconUrl": "<省略>",
      "internationCode": "86",
      "inviteVid": 1000000000000005,
      "isNameVerified": true,
      "isSyncInnerPosition": true,
      "job": "",
      "mainPartyId": 1000000000000003,
      "mobile": "",
      "mobileAreaCode": 0,
      "name": "示例昵称",
      "nameVerifyStatus": 1,
      "number": "",
      "personalWorkType": 0,
      "phone": "",
      "position": "",
      "realName": "示例用户",
      "superiors": [
        {}
      ],
      "tencentInfo": {},
      "uin": 1000000000000001,
      "unionId": "<省略>",
      "vCode": "<省略>",
      "vCorpUseStatus": 1000,
      "xcxStyle": 0
    },
    "level": 3,
    "vid": 1000000000000001
  }
}

接入步骤

在青鸾开发者控制台创建或查看 API Key。
在「实例与回调」接入企业微信账号，取得 appid。
请求头携带 QL-Key，按当前契约提交 JSON 请求。
读取响应中的 code；仅当 code=0 时按成功流程处理。

把企业微信能力接入你的系统

从 API Key、appid 到首个 code=0 响应，可在开发者控制台完成配置与验证。

打开开发者控制台