feishu-approval

Feishu Approval

Create and query approval instances via the Approval API.

Base URL: https://open.feishu.cn/open-apis/approval/v4

Authentication and Token Acquisition

From the feishu_skills root directory, execute the shared script:

TOKEN="$(./scripts/get_feishu_token.sh)"

The request header uniformly uses Authorization: Bearer ${TOKEN}。

If the business API returns token invalid, expired, or 401, force a refresh and retry the original request only once:

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

Environment Variables:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

Local Cache: ./.feishu_token_cache.json(reused directly if not expired, refreshed 5 minutes early by default)

---

Approval Instances

API	Endpoint	Method	Request Body Example	Description
Create Instance	/instances	POST	{"approval_code":"7C46...","user_id":"ou_xxx","form":"{\"widget1\":\"value1\"}"}	Initiate approval
Query Instance	/instances/{instance_id}	GET	-	Get approval status
Approval Action	/instances/{instance_id}/approve	POST	{"comment":"同意","task_id":"xxx"}	Approve/Reject approval
Withdraw Approval	/instances/{instance_id}/cancel	POST	{"user_id":"ou_xxx"}	Applicant withdraws
Transfer Approval	/instances/{instance_code}/transfer	POST	{"user_id":"ou_xxx","transfer_user_id":"ou_yyy","comment":"转交"}	Transfer to another person
Urge Approval	/instances/{instance_id}/urge	POST	-	Send reminder
Get Instance List	/instances	GET	Query parameters:page_size=50&page_token=xxx&user_id=ou_xxx	Supports filter parameters (pagination)
Query Instance Details	/instances/detail	POST	{"instance_code":"xxx"}	Query complete details

Create Instance:

{
  "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85",
  "user_id": "ou_xxx",
  "form": "{\"widget1\":\"value1\"}"
}

---

Approval Tasks

API	Endpoint	Method	Request Body Example	Description
Get Task List	/tasks	GET	-	Query pending tasks
Get Task Details	/tasks/{task_id}	GET	-	Query task details
Approve Task	/tasks/{task_id}/approve	POST	{"comment":"同意"}	Process approval task
Transfer Task	/tasks/{task_id}/transfer	POST	{"transfer_user_id":"ou_xxx"}	Transfer task

---

Approval Definitions

API	Endpoint	Method	Request Body Example	Description
Get Definition List	/approvals	GET	-	Query all approval templates
Get Definition Details	/approvals/{approval_code}	GET	-	Query template details
Get Definition Form	/approvals/{approval_code}/forms	GET	-	Query form field definitions

---

Approval CC

API	Endpoint	Method	Request Body Example	Description
Get CC List	/cc	GET	-	Query approvals CC'd to me
Mark CC as Read	/cc/{instance_id}/read	POST	-	Mark CC as read

---

Approval Comments

API	Endpoint	Method	Request Body Example	Description
Add Comment	/instances/{instance_id}/comments	POST	{"content":"评论内容","user_id":"ou_xxx"}	Add approval comment
Get Comments	/instances/{instance_id}/comments	GET	-	Query comment list

---

Common Parameter Descriptions

user_id_type: User ID type

• open_id(default)
• user_id
• union_id

Pagination Parameters:

• page_size: Number per page (default 20, maximum 100)
• page_token: Pagination token

Instance Status:

• PENDING: Under approval
• APPROVED: Approved
• REJECTED: Rejected
• CANCELED: Withdrawn
• DELETED: Deleted

---

Test Example

Get Approval Definition List:

curl -X GET "https://open.feishu.cn/open-apis/approval/v4/approvals?page_size=10" \
  -H "Authorization: Bearer ${TOKEN}"

Create approval instance:

curl -X POST "https://open.feishu.cn/open-apis/approval/v4/instances" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85",
    "user_id": "ou_xxx",
    "form": "{\"widget1\":\"请假3天\"}"
  }'

Query instance list:

curl -X GET "https://open.feishu.cn/open-apis/approval/v4/instances?page_size=20&user_id=ou_xxx" \
  -H "Authorization: Bearer ${TOKEN}"

---

Best practices

1. First obtain the approval definition(confirm the form field)
2. form must be a stringified JSON
3. Approval operations require approver permissions
4. Paginated query: use page_token for pagination with large amounts of data
5. user_id is required: both creating an instance and querying the list require specifying user_id