Feishu Contact
- 69 installs
- 65 repo stars
- Updated March 26, 2026
- alextangson/feishu_skills
Feishu Contact is a Claude skill that wraps the Feishu (Lark) Contact v3 API for member search, department and role management, and conversion between open_id, user_id, and union_id.
About
This skill wraps the Feishu (Lark) Contact v3 API to manage an organization directory and convert user IDs. It covers member search, department, user group, job-family, and role management, plus conversion between open_id, user_id, and union_id. A developer uses it to automate org-directory tasks and ID resolution in Feishu. The docs are written in Chinese.
- Wraps the Feishu (Lark) Contact v3 API for member search, department and role management, and org events
- Converts between open_id, user_id, and union_id in one call
- Documents 17 contact change events and token acquisition
Feishu Contact by the numbers
- 69 all-time installs (skills.sh)
- Ranked #952 of 2,715 Automation & Workflows skills by installs in the Skillselion catalog
- Data as of Jul 28, 2026 (Skillselion catalog sync)
feishu-contact capabilities & compatibility
Requires a Feishu app (FEISHU_APP_ID and FEISHU_APP_SECRET) to obtain a tenant access token
- Use cases
- orchestration · project management
- Pricing
- Bring your own API key
What feishu-contact says it does
通过 Contact v3 API 实现成员搜索、部门管理和 ID 转换。
**Base URL**: `https://open.feishu.cn/open-apis/contact/v3`
npx skills add https://github.com/alextangson/feishu_skills --skill feishu-contactAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 69 |
|---|---|
| repo stars | ★ 65 |
| Last updated | March 26, 2026 |
| Repository | alextangson/feishu_skills ↗ |
What it does
Manage Feishu org directory and convert user IDs via the Contact v3 API.
Who is it for?
Managing Feishu/Lark org directory and converting user IDs via API
When should I use this skill?
You need to search Feishu members, manage departments/roles, or convert user IDs
What you get
Members searched, departments and roles managed, and IDs converted via Contact v3
By the numbers
- 3 ID types (open_id, user_id, union_id)
- 17 contact change events
Files
飞书组织架构与 ID 转换
通过 Contact v3 API 实现成员搜索、部门管理和 ID 转换。
---
API 基础
Base URL: https://open.feishu.cn/open-apis/contact/v3 认证: Authorization: Bearer {tenant_access_token}
认证与 Token 获取
从 feishu_skills 根目录执行共享脚本：
TOKEN="$(./scripts/get_feishu_token.sh)"请求头统一使用 Authorization: Bearer ${TOKEN}。
如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：
TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"环境变量:
FEISHU_APP_IDFEISHU_APP_SECRET
本地缓存: ./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）
---
成员查询
| API | 端点 | 说明 |
|---|---|---|
| 搜索成员 | GET /users/batch_get_id | 通过邮箱/手机号获取 OpenID |
| 获取职务 | GET /job_titles/{id} | 需在管理后台预先维护 |
---
部门管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 获取部门 | /departments/{department_id} | GET | - | 查询单个部门详情 |
| 获取部门列表 | /departments | GET | - | 支持 parent_department_id 参数 |
| 获取父部门路径 | /departments/{department_id}/parent | GET | - | 获取部门层级路径 |
| 创建部门 | /departments | POST | {"name":"新部门","parent_department_id":"0"} | 需管理员权限 |
| 更新部门 | /departments/{department_id} | PUT | {"name":"更新后的名称"} | 修改部门信息 |
| 删除部门 | /departments/{department_id} | DELETE | - | 删除空部门 |
| 入职成员 | /users | POST | {"name":"张三","mobile":"138...","department_ids":["od_xxx"]} | 创建用户 |
| 更新用户 | /users/{user_id} | PUT | {"name":"新名字"} | 修改用户信息 |
| 删除用户 | /users/{user_id} | DELETE | - | 移除用户 |
| 获取用户列表 | /users | GET | - | 支持 department_id 过滤 |
⚠️ 创建部门和入职成员需最高权限，建议预发环境测试。
---
用户组管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 获取用户组列表 | /groups | GET | - | 查询所有用户组 |
| 获取用户组 | /groups/{group_id} | GET | - | 查询单个用户组 |
| 创建用户组 | /groups | POST | {"name":"项目组","description":"描述"} | 创建新用户组 |
| 更新用户组 | /groups/{group_id} | PUT | {"name":"新名称"} | 修改用户组 |
| 删除用户组 | /groups/{group_id} | DELETE | - | 删除用户组 |
| 获取组成员 | /groups/{group_id}/members | GET | - | 查询组成员列表 |
| 添加组成员 | /groups/{group_id}/members | POST | {"member_id":"ou_xxx","member_type":"user"} | 添加用户到组 |
| 移除组成员 | /groups/{group_id}/members/{member_id} | DELETE | - | 从组移除用户 |
---
职级管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 获取职级列表 | /job_families | GET | - | 查询所有职级 |
| 获取职级 | /job_families/{job_family_id} | GET | - | 查询单个职级 |
| 创建职级 | /job_families | POST | {"name":"高级工程师"} | 创建新职级 |
| 更新职级 | /job_families/{job_family_id} | PUT | {"name":"资深工程师"} | 修改职级 |
| 删除职级 | /job_families/{job_family_id} | DELETE | - | 删除职级 |
---
角色管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 获取角色列表 | /roles | GET | - | 查询所有角色 |
| 创建角色 | /roles | POST | {"role_name":"管理员"} | 创建新角色 |
| 更新角色 | /roles/{role_id} | PUT | {"role_name":"超级管理员"} | 修改角色名称 |
| 删除角色 | /roles/{role_id} | DELETE | - | 删除角色 |
| 获取角色成员 | /roles/{role_id}/members | GET | - | 查询角色下所有成员 |
| 批量添加角色成员 | /roles/{role_id}/members/batch_create | POST | {"members":[{"member_id":"ou_xxx","member_type":"user"}]} | 批量添加成员 |
| 批量删除角色成员 | /roles/{role_id}/members/batch_delete | POST | {"members":[{"member_id":"ou_xxx"}]} | 批量移除成员 |
---
ID 转换（核心）
飞书三种 ID 体系：
| ID 类型 | 说明 | 使用场景 |
|---|---|---|
open_id | 应用内唯一 | 同一应用内识别用户 |
user_id | 企业内唯一 | 企业内部系统对接 |
union_id | 跨应用唯一 | 同一开发者的多个应用间 |
Contact v3 ID 转换
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 批量获取用户 ID | /users/batch_get_id | POST | {"emails":["a@b.com"],"mobiles":["138xxx"]} | 通过邮箱/手机获取 OpenID |
| 批量获取部门 ID | /departments/batch_get_id | POST | {"department_ids":["od_xxx"]} | 部门 ID 转换 |
| 获取用户 | /users/{user_id} | GET | - | 通过 ID 获取用户信息 |
| 获取用户信息（批量） | /users/batch_get | GET | - | 参数：user_ids=ou_1,ou_2 |
ID 转换最佳实践：
通过 GET /users/{user_id} 接口可一次性获取用户的所有 ID 类型（open_id/user_id/union_id），无需单独转换。
示例：
GET /contact/v3/users/ou_xxx?user_id_type=open_id响应包含：
{
"data": {
"user": {
"open_id": "ou_xxx",
"user_id": "7c43cd5f",
"union_id": "on_xxx"
}
}
}---
其他
| API | 端点 | 方法 | 说明 |
|---|---|---|---|
| 获取职务列表 | /job_titles | GET | 查询所有预设职务 |
| 获取职务 | /job_titles/{job_title_id} | GET | 查询单个职务详情 |
| 获取办公地点 | /places | GET | 用于人员地理分布分析 |
| 获取人员类型 | /employee_types | GET | 查询人员类型列表 |
| 获取自定义属性 | /custom_attr_events | GET | 查询自定义属性变更事件 |
| 获取授权范围 | /scopes | GET | 查询应用可访问的部门/用户范围 |
| 外部成员访问 | /application/v1/applications/{app_id}/user_usable | GET | 控制供应商/外包访问权限 |
事件订阅
通讯录支持 17 个变更事件：
| 事件类型 | 说明 |
|---|---|
contact.user.created_v3 | 用户创建 |
contact.user.updated_v3 | 用户信息更新 |
contact.user.deleted_v3 | 用户删除 |
contact.dept.created_v3 | 部门创建 |
contact.dept.updated_v3 | 部门更新 |
contact.dept.deleted_v3 | 部门删除 |
contact.employee_type.created_v3 | 人员类型创建 |
contact.employee_type.updated_v3 | 人员类型更新 |
contact.employee_type.deleted_v3 | 人员类型删除 |
contact.job_family.created_v3 | 职级创建 |
contact.job_family.updated_v3 | 职级更新 |
contact.job_family.deleted_v3 | 职级删除 |
---
最佳实践
1. ID 转换优先用 Spark API（更简洁） 2. 缓存常用 ID（减少 API 调用） 3. 组织架构变更必须预发测试
Related skills
Agent BrowserGive their coding agent reliable, high-fidelity control over any website or Electron desktop app.591k39.6k
Lark ApprovalLet their AI coding agent create, read, update, and approve items in Lark (Feishu) approval workflows without leaving the coding environment.494kLark EventHandle Feishu/Lark bot events, webhooks, and subscription callbacks in agent-driven backend code.493kLark Workflow Meeting SummaryAutomatically generate structured meeting summaries and action items from Lark/Feishu calls without manual note-taking.492kLark Workflow Standup ReportAutomatically generate and post daily standup reports in Lark/Feishu from their workflow and activity data.492k
Twitter AutomationAutomate X/Twitter posts, scheduling, and engagement via X API integration441k669FAQ
What can feishu-contact do?
Search members, manage departments, user groups, job families and roles, and convert between open_id, user_id, and union_id via the Contact v3 API.
How does ID conversion work?
A single GET /users/{user_id} call returns all three ID types (open_id, user_id, union_id) so no separate conversion is needed.