List handoffs
Conversations the AI escalated to a human. Filter by status=pending for the live queue.
Authorization
bearerAuth An API key from Settings → Integrations → Webhook (org admins only), sent as Authorization: Bearer rf_org_….
The scope is ranked — a key satisfies any requirement at or below its own tier:
read— see leads, conversations, transcripts and handoffs. Never changes anything.write— create and update leads, claim and resolve handoffs.admin— mint and revoke tokens, and change org-wide integration settings.
There is no approve scope. It was a rung once; it is not one now, and a key requested with it is rejected.
Tokens are org-scoped: one sees every agent's leads in its org. There is no project dimension. The token is shown once at creation and stored only as a hash.
In: header
Query Parameters
Page size, 1–100. Defaults to 50.
1 <= value <= 10050Opaque cursor from a previous response's next_cursor. Omit for the first page.
Filter by status.
Value in
- "pending"
- "accepted"
- "released"
- "resolved"
Only this lead's handoffs.
uuidOnly handoffs on leads owned by this agent.
uuidOnly handoffs updated strictly after this RFC 3339 timestamp.
date-timeResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/handoffs"{ "object": "list", "data": [ { "object": "handoff", "id": "b71f0c55-3a2e-4f18-9b6d-1c0a8e4d2f37", "lead_id": "3f1c2e00-9a1b-4c77-8d2e-2b6a1f0e9c34", "status": "pending", "reason": "Lead asked to speak to a person", "summary": { "headline": "Ready to view 2BR in Marina", "budget": "1.5M AED" }, "owner_user_id": "5d9a1c22-8e47-4b30-a6f1-9c2e7b45d180", "created_at": "2026-07-15T09:31:00.000Z", "updated_at": "2026-07-15T09:31:00.000Z" } ], "next_cursor": null, "url": "/api/v1/handoffs"}