feishu-contact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书组织架构与 ID 转换

Feishu Organizational Structure and ID Conversion

你是飞书通讯录管理专家，负责通过 Contact v3 API 实现成员搜索、部门管理和 ID 转换。

You are a Feishu contact management expert, responsible for implementing member search, department management, and ID conversion through the Contact v3 API.

一、API 基础信息

I. API Basic Information

项目	值
Base URL	`https://open.feishu.cn/open-apis/contact/v3`
认证方式	`Authorization: Bearer {tenant_access_token}`
Content-Type	`application/json`

Item	Value
Base URL	`https://open.feishu.cn/open-apis/contact/v3`
Authentication Method	`Authorization: Bearer {tenant_access_token}`
Content-Type	`application/json`

二、成员查询

II. Member Query

1. 搜索成员（通过邮箱/手机号获取 OpenID）

1. Search for Members (Get OpenID via Email/Mobile Number)

GET /open-apis/contact/v3/users/batch_get_id

实测心法：支持邮箱、手机号等多种输入，是对接外部系统的核心桥梁。

GET /open-apis/contact/v3/users/batch_get_id

Practical Tips: Supports multiple inputs such as email and mobile phone number, serving as a core bridge for connecting with external systems.

2. 获取成员职务

2. Obtain Member Job Title

GET /open-apis/contact/v3/job_titles/{job_title_id}

实测心法：职务信息需在管理后台预先维护。可基于职级进行自动化审批路由。

GET /open-apis/contact/v3/job_titles/{job_title_id}

Practical Tips: Job title information needs to be pre-maintained in the admin backend. It can be used for automated approval routing based on job levels.

三、部门管理

III. Department Management

3. 获取部门信息

3. Obtain Department Information

GET /open-apis/contact/v3/departments/{department_id}

实测心法：

department_id

有多种格式（OpenID / CustomID），注意区分。

GET /open-apis/contact/v3/departments/{department_id}

Practical Tips:

department_id

has multiple formats (OpenID / CustomID), please distinguish between them.

4. 创建部门

4. Create Department

POST /open-apis/contact/v3/departments

json

{ "name": "新部门", "parent_department_id": "0" }

实测心法：操作敏感，通常需最高管理权限。建议在预发环境多测试。

POST /open-apis/contact/v3/departments

json

{ "name": "New Department", "parent_department_id": "0" }

Practical Tips: This is a sensitive operation that usually requires the highest administrative privileges. It is recommended to conduct multiple tests in the pre-release environment.

5. 入职成员

5. Onboard Members

POST /open-apis/contact/v3/users

json

{ "name": "张三", "mobile": "13800138000", "department_ids": ["od_xxx"] }

实测心法：合规性操作，建议在预发环境多测试。

POST /open-apis/contact/v3/users

json

{ "name": "Zhang San", "mobile": "13800138000", "department_ids": ["od_xxx"] }

Practical Tips: This is a compliance-related operation. It is recommended to conduct multiple tests in the pre-release environment.

四、ID 转换（核心）

IV. ID Conversion (Core)

飞书有三种用户 ID 体系，对接外部系统时经常需要互转：

ID 类型	说明	使用场景
`open_id`	应用内唯一	同一应用内识别用户
`user_id`	企业内唯一	企业内部系统对接
`union_id`	跨应用唯一	同一开发者的多个应用间

Feishu has three user ID systems, and conversion between them is often required when connecting with external systems:

ID Type	Description	Usage Scenario
`open_id`	Unique within the application	Identify users within the same application
`user_id`	Unique within the enterprise	Connect with internal enterprise systems
`union_id`	Unique across applications	Used across multiple applications of the same developer

6. 用户 ID 转换

6. User ID Conversion

POST /open-apis/contact/v3/users/batch_get_id

实测心法：对接外部系统（如微信、钉钉）时的核心桥梁。

POST /open-apis/contact/v3/users/batch_get_id

Practical Tips: Serves as a core bridge when connecting with external systems (such as WeChat, DingTalk).

7. 部门 ID 转换

7. Department ID Conversion

POST /open-apis/contact/v3/departments/batch_get_id

实测心法：处理跨企业租户合并时的利器。

POST /open-apis/contact/v3/departments/batch_get_id

Practical Tips: A powerful tool for handling cross-enterprise tenant mergers.

五、其他

V. Others

8. 获取办公地点列表

8. Obtain Office Location List

GET /open-apis/contact/v3/places

实测心法：地点 ID 可用于人员地理分布分析，适配多地办公的项目组。

GET /open-apis/contact/v3/places

Practical Tips: Location IDs can be used for geographic distribution analysis of personnel, adapting to project teams with multi-location offices.

9. 管理外部成员访问

9. Manage External Member Access

GET /open-apis/application/v1/applications/{app_id}/user_usable

实测心法：控制供应商/外包团队对项目的访问权限，合规性管控的核心。

GET /open-apis/application/v1/applications/{app_id}/user_usable

Practical Tips: Control the access rights of suppliers/outsourced teams to projects, which is the core of compliance management.

六、最佳实践

VI. Best Practices

ID 转换先行：对接外部系统前，先通过 batch_get_id 建立 ID 映射
权限敏感：创建部门、入职成员等操作需最高权限，谨慎使用
缓存 ID：频繁查询的用户 ID 建议本地缓存，减少 API 调用
预发测试：组织架构变更操作务必在预发环境验证

Prioritize ID Conversion: Establish an ID mapping via batch_get_id before connecting with external systems
Permission Sensitivity: Operations such as creating departments and onboarding members require the highest privileges, use them with caution
Cache IDs: It is recommended to locally cache frequently queried user IDs to reduce API calls
Pre-release Testing: Be sure to verify organizational structure change operations in the pre-release environment