Appearance
联系人
通讯录同步、详情、搜索、加好友、备注、标签。
本模块接口全部 POST，请求地址 = {BASE_URL} + 路径。
| 接口 | 用途 | 安全级别 |
|---|---|---|
同步通讯录 ID 列表/wx-api/api/contact/getSyncList | 拉取内部通讯录（成员 + 部门）的「节点列表 + 游标」，是通讯录同步的第一步。 | 只读 |
批量获取通讯录详细信息/wx-api/api/contact/fetchUsersProfileBatch | 把 getSyncList 的节点列表换成每个节点的详细资料（成员资料 / 部门信息）。 | 只读 |
获取用户信息详情/wx-api/api/contact/getUserProfileDetail | 按用户 id 列表直接查最全的用户资料（内部成员或外部联系人均可）。 | 只读 |
手机号搜索/wx-api/api/contact/phoneNumberSearch | 按手机号搜索用户，拿到添加好友所需的票据（wxTicket）与身份（openid / uin / corpId），供后续加好友接口使用。 | 只读 |
通过手机号添加个微/wx-api/api/contact/phoneNumberAddWechat | 用 phoneNumberSearch 拿到的票据，向对方的个人微信发起好友申请。 | 写操作 |
通过手机号添加企微/wx-api/api/contact/phoneNumberAddWework | 用 phoneNumberSearch 拿到的企微身份与票据，向对方的企业微信发起好友/客户申请。 | 写操作 |
同意新客户/wx-api/api/contact/agreeToNewCustomer | 对方主动申请添加你为好友/客户时，调用本接口同意。 | 写操作 |
更新外部联系人信息/wx-api/api/contact/updateExternalContactInfo | 修改某个外部联系人（客户）的备注、公司、真实备注、备注手机号等。 | 写操作 |
删除联系人/wx-api/api/contact/delete | 删除一个联系人（解除好友关系）。 | 高风险 |
设置同事备注/wx-api/api/contact/setColleagueRemark | 给内部成员（同事）设置备注 / 描述。 | 写操作 |
添加名片/wx-api/api/contact/addCard | 通过收到的「个人名片消息」添加对方为好友。 | 写操作 |
添加群成员为好友/wx-api/api/contact/addRoomMember | 把群内某成员添加为自己的好友（不是把人拉进群）。 | 写操作 |
同步外部数据（非企业）/wx-api/api/contact/syncExternal | 增量同步外部联系人（客户）数据；收到回调 contentType=2131（外部联系人变更）后调用拉增量。 | 只读 |
更新用户标签/wx-api/api/contact/updateLabel | 给某个用户打 / 去 / 改标签（操作的是「用户 ↔ 标签」的关联）。 | 写操作 |
安全级别与「实测 日期」标记的含义见接口总览的图例。
企微通讯录 / 客户数据不是一次性拉全，而是「先拿 id 列表 + 游标，再按 id 拉详情；之后靠回调驱动增量」的两段式。
内部通讯录
getSyncList—— 拿「节点列表」nodeList[]，每项是一个通讯录节点{type, vid?, partyId, seq}：type= 节点类型：1= 成员（个人，带vid）/2= 部门（无vid，只有partyId）。vid= 联系人 id（成员的唯一 id，等于其uin）。partyId= 部门/组织 id（该成员所在部门；type=2时即部门自身 id）。seq= 同步游标（单条记录的版本号，int64，值越大越新）。- 同时返回
svrVersion（整体增量版本号，字符串）。首次传空svrVersion= 全量；下次把上次的svrVersion回传 = 增量。
fetchUsersProfileBatch—— 把nodeList原样传入（可分批），换回每个节点的详细资料patchList[]（成员 →member对象，部门 →department对象）。- 需要单个/少量用户的完整资料时，用
getUserProfileDetail（直接按vid/uin列表查，返回更全的info，含level）。
外部联系人（客户）
客户 = 外部联系人。
syncExternal—— 增量拉外部联系人（客户）列表。seq是游标（首次0），返回data.{list[], hasNext, seq}；hasNext=true时用返回的新seq继续翻页，直到hasNext=false。建议持久化最新seq。- 回调驱动：客户资料变更时，系统会推送
contentType = 2131（外部联系人信息发生变更）的系统消息，收到后再调一次syncExternal拉增量；个人标签变更推2186，去调标签同步接口。报文见回调字典 · 类型速查表。 - 添加客户 / 手机号加好友：先
phoneNumberSearch拿wxTicket等票据，再走phoneNumberAddWechat（个微）/phoneNumberAddWework（企微）；对方申请加你时用agreeToNewCustomer同意。
用户对象字段字典
member / info / userInfo / contactInfo 这几个「用户对象」字段高度重合，统一在此说明，后续各接口的响应表只列顶层结构并回指本字典。
| 字段 | 类型 | 含义 |
|---|---|---|
uin | int64 | 用户唯一 id；内部成员等于其 vid，外部客户等于 id。int64，注意精度。 |
name | string | 昵称 / 显示名 |
realName | string | 实名（已脱敏为「张**」） |
englishName | string | 英文名 |
alias | string | 别名 / 花名 |
mobile | string | 手机号（仅内部同事和已授权场景可见） |
phone | string | 电话（外部对象常为空） |
internationCode | string | 国际区号，如 86 |
emailAddr | string | 个人邮箱 |
bizMail | string | 企业邮箱 |
birthday | string | 生日 YYYY-MM-DD HH:MM:SS |
gender | int | 性别：1 男 / 2 女 / 0 未知 |
job / position | string | 职位 / 职务 |
externPosition | string | 对外展示职位，base64 编码（如 5oC757uP55CG→「总经理」） |
number | string | 工号 |
iconUrl | string | 头像 URL |
corpId | int64 | 所属企业 id |
partyId | int64 | 所在部门 id |
mainPartyId | int64 | 主部门 id |
dispOrder / partyMemberDispOrder | int | 通讯录 / 部门内显示排序 |
isNameVerified | bool | 是否已实名认证 |
nameVerifyStatus | int | 实名认证状态（观测 1） |
inviteVid | int64 | 邀请人 vid |
vCode | string | 名片/验证码（形如 vc31f1...） |
unionId | string | 微信 unionId（跨应用用户标识） |
customInfo / externalCustomInfo | object | 自定义字段集合（常为空对象） |
holidayInfo | object | 休假信息（holidayStatus / holidayDesc / ...） |
tencentInfo | object | 腾讯生态相关（常为空对象） |
isSyncInnerPosition | bool | 是否同步内部职位 |
hash | int | 数据 hash（变更检测用） |
createSource | int | 创建来源（外部客户常见） |
superiors | array | 上级链（汇报关系），元素为对象。 |
xcxCorpAddress | string | 小程序名片-企业地址，base64 编码。 |
businessDesc | object | 业务描述自定义字段：{fieldName(base64), fieldId(base64,如 busi_desc), fieldType}；内部成员/外部客户均可能出现。 |
corpDescInfo | object | 企业描述信息（常为空对象 {}）。 |
corpDesc | object / string | 企业描述（仅 getUserProfileDetail 的部分 info 出现）。 |
holidayInfo.vacationSyncType | int | holidayInfo 内字段：休假同步类型。 |
以下字段含义未完全公开，原样透传即可
| 字段 | 类型 | 说明 |
|---|---|---|
mobileAreaCode | int | 手机区号（常为 0） |
bindEmailStatus | int | 邮箱绑定状态（观测到 2=已绑定 / 1） |
gid | int64 | 全局 id（跨企业标识） |
attr / attr2 / attr3 | int | 属性位掩码（bitmask） |
bizUin | int64 | 企业 uin |
vCorpUseStatus | int | 企业使用状态（观测 1000） |
xcxStyle | int | 小程序名片样式 |
personalWorkType | int | 个人工作类型 |
schoolUserType / collegeIdentity | int | 学校 / 高校身份类型 |