List leads
Search and page through every lead in your org, newest-updated first. Use external_ref_system + external_ref_id to look a lead up by your own CRM's identifier.
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 qualification stage.
Value in
- "new"
- "qualifying"
- "qualified"
- "meeting_booked"
- "nurture"
- "not_qualified"
- "closed"
Filter by the agent's routing decision.
Value in
- "hotLead"
- "nurture"
- "needsHuman"
- "notQualified"
Only leads owned by this agent.
uuidOnly leads with at least one conversation on this channel (whatsapp, web, gmail…). Note this differs from the response's channel, which is the most recent conversation.
Only leads updated strictly after this RFC 3339 timestamp — the incremental-sync filter.
date-timeArchived leads are excluded by default.
"exclude"Value in
- "exclude"
- "include"
- "only"
Case-insensitive substring match on name, phone, or email.
Must be sent together with external_ref_id.
Must be sent together with external_ref_system.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/leads"{ "object": "list", "data": [ { "object": "lead", "id": "3f1c2e00-9a1b-4c77-8d2e-2b6a1f0e9c34", "name": "Jane Buyer", "email": null, "phone": "+971501234567", "channel": "whatsapp", "qualification_stage": "qualified", "route_target": "hotLead", "profile": { "budget": "1.5M AED", "bedrooms": 2, "area": "Dubai Marina" }, "external_ref": { "system": "my-crm", "id": "crm-123", "url": "https://crm.example.com/leads/123" }, "conversation_url": "https://replyfirst.ae/app/chats/3f1c2e00-9a1b-4c77-8d2e-2b6a1f0e9c34", "created_at": "2026-07-15T09:30:00.000Z", "updated_at": "2026-07-15T09:31:12.000Z" } ], "next_cursor": "MjAyNi0wNy0xNVQwOTozMToxMi4wMDBafDNmMWMyZTAw", "url": "/api/v1/leads"}