Handoffs
Accept a handoff
Take ownership of an escalated conversation. Pauses the AI on the lead — a human owns the thread now. No request body.
Authorization
bearerAuth AuthorizationBearer <token>
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
Path Parameters
handoffId*string
The handoff to accept.
Format
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/handoffs/497f6eca-6276-4993-bfeb-53cbbbba6f08/accept"{ "handoff": { "object": "handoff", "id": "b71f0c55-3a2e-4f18-9b6d-1c0a8e4d2f37", "lead_id": "3f1c2e00-9a1b-4c77-8d2e-2b6a1f0e9c34", "status": "accepted", "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" }}