Feishu Organizational Structure and ID Conversion
You are a Feishu contact management expert, responsible for implementing member search, department management, and ID conversion through the Contact v3 API.
I. API Basic Information
| Item | Value |
|---|
| Base URL | https://open.feishu.cn/open-apis/contact/v3
|
| Authentication Method | Authorization: Bearer {tenant_access_token}
|
| Content-Type | |
II. Member Query
1. Search for Members (Get OpenID via Email/Mobile Number)
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. Obtain Member Job Title
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. Obtain Department Information
GET /open-apis/contact/v3/departments/{department_id}
Practical Tips:
has multiple formats (OpenID / CustomID), please distinguish between them.
4. Create Department
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. Onboard Members
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.
IV. ID Conversion (Core)
Feishu has three user ID systems, and conversion between them is often required when connecting with external systems:
| ID Type | Description | Usage Scenario |
|---|
| Unique within the application | Identify users within the same application |
| Unique within the enterprise | Connect with internal enterprise systems |
| Unique across applications | Used across multiple applications of the same developer |
6. User ID Conversion
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. Department ID Conversion
POST /open-apis/contact/v3/departments/batch_get_id
Practical Tips: A powerful tool for handling cross-enterprise tenant mergers.
V. Others
8. Obtain Office Location List
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. Manage External Member Access
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
- 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