Reply First

Record a lead. Record-only: it is created at stage new, no message is sent and no AI run starts — the lead is picked up when the contact writes in (matched by phone/email). Idempotent per owning agent on phone/email: a repeat returns 200 with created: false and the existing lead. Does NOT emit the lead.created webhook (your system already knows).

Authorization

bearerAuth

AuthorizationBearer <token>

Org-scoped token, created at Settings → Integrations → Webhook. Looks like rf_org_…, shown once, sent as Authorization: Bearer rf_org_…. Rate limit: 120 requests/minute per token.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Contact name.

Length1 <= length <= 200

phone?string

Normalized to E.164. At least one of phone/email is required.

Length5 <= length <= 32

email?string

At least one of phone/email is required.

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Formatemail

profile?

Validated against the org's vertical pack; unknown keys → 422.

external_ref?

owner_user_id?string

The owning agent (uuid). Provide this OR owner_email, not both.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

owner_email?string

The owning agent by email. Falls back to the token creator if omitted.

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/leads" \  -H "Content-Type: application/json" \  -d '{    "name": "Jane Buyer",    "phone": "+971501234567",    "email": "[email protected]",    "profile": {      "budget": "1.5M AED"    },    "external_ref": {      "system": "my-crm",      "id": "crm-123",      "url": "https://crm.example.com/leads/123"    },    "owner_email": "[email protected]"  }'

{  "created": false,  "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"  }}

{  "created": true,  "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"  }}

{  "error": "Invalid JSON body"}

{  "error": "Unauthorized"}

{  "error": "Provide at least one of phone, email."}

{  "error": "Rate limit exceeded"}

Create a lead

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`