Skip to main content
Push leads from your pipeline into a sub-account. Leads can optionally be enrolled in a follow-up sequence automatically.

​
Import a Lead

POST /accounts/:id/leads
​
phone
string
required
Phone number (E.164 or 10-digit). Auto-normalized.
​
name
string
Full name
​
first_name
string
First name
​
last_name
string
Last name
​
email
string
Email address
​
company
string
Company or employer
​
notes
string
Free-text notes
​
source
string
Lead source label (e.g., application, collection)
​
external_id
string
Your internal ID for deduplication
​
property_address
string
Property address
​
auto_sequence
boolean
default:"false"
Start the default sequence immediately
​
metadata
object
Arbitrary key-value pairs stored on the lead
curl -X POST https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "name": "John Doe",
    "email": "[email protected]",
    "source": "application",
    "external_id": "app_98765",
    "auto_sequence": true,
    "notes": "Stalled at document upload step"
  }'
Response: 201 Created 
{
  "success": true,
  "action": "created",
  "lead": {
    "phone": "+14155551234",
    "name": "John Doe",
    "email": "[email protected]",
    "source": "application",
    "external_id": "app_98765",
    "status": "new",
    "sequence_enrolled": true,
    "created_at": "2026-02-15T10:30:00Z"
  }
}
Deduplication: If a lead with the same phone or external_id already exists in the account, existing fields are preserved and only empty fields are filled from the new payload. The response action will be "updated" or "skipped".

​
Bulk Import

POST /accounts/:id/leads/bulk Import up to 1,000 leads in a single request. 
curl -X POST https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads/bulk \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "phone": "+14155551234", "name": "John Doe", "auto_sequence": true },
      { "phone": "+14155555678", "name": "Jane Smith", "auto_sequence": true }
    ]
  }'
Response: 200 OK 
{
  "success": true,
  "imported": 2,
  "updated": 0,
  "skipped": 0,
  "errors": []
}

​
List Leads

GET /accounts/:id/leads
​
limit
integer
default:"50"
Max results (1-250)
​
offset
integer
default:"0"
Pagination offset
​
status
string
Filter: new, contacted, qualified, converted, lost
​
search
string
Search name, email, phone
​
source
string
Filter by source label
curl https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads?status=qualified&limit=20 \
  -H "X-Partner-Key: pk_live_abc123def456..."
Response: 200 OK 
{
  "leads": [
    {
      "phone": "+14155551234",
      "name": "John Doe",
      "email": "[email protected]",
      "status": "qualified",
      "source": "application",
      "checklist_progress": 0.75,
      "last_message_at": "2026-02-14T15:30:00Z",
      "created_at": "2026-02-10T09:00:00Z"
    }
  ],
  "total": 342,
  "limit": 20,
  "offset": 0
}

​
Get Lead

GET /accounts/:id/leads/:phone Returns full lead details including checklist status and conversation summary. 
{
  "phone": "+14155551234",
  "name": "John Doe",
  "email": "[email protected]",
  "company": "Doe Industries",
  "status": "qualified",
  "source": "application",
  "external_id": "app_98765",
  "checklist": {
    "progress": 0.75,
    "items": [
      { "name": "Government ID", "type": "document", "status": "completed", "collected_at": "2026-02-12T14:00:00Z" },
      { "name": "3 Months Bank Statements", "type": "document", "status": "completed" },
      { "name": "T4 Slip", "type": "document", "status": "pending" },
      { "name": "Email Address", "type": "email", "status": "completed", "value": "[email protected]" }
    ]
  },
  "conversation": {
    "message_count": 12,
    "last_message_at": "2026-02-14T15:30:00Z",
    "summary": "Borrower submitted ID and bank statements. Waiting on T4 slip. Expressed interest in 24-month term.",
    "needs_handoff": false
  },
  "sequence": {
    "name": "Application Recovery",
    "status": "active",
    "current_step": 3,
    "total_steps": 5
  }
}

​
Update Lead

PATCH /accounts/:id/leads/:phone Update lead fields. Only provided fields are changed — omitted fields are left as-is. 
curl -X PATCH https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads/+14155551234 \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "converted",
    "notes": "Application approved and funded"
  }'

​
Delete Lead

DELETE /accounts/:id/leads/:phone Removes a lead and all associated data (checklist progress, sequence enrollment). Conversation history is preserved. 
curl -X DELETE https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads/+14155551234 \
  -H "X-Partner-Key: pk_live_abc123def456..."
Response: 200 OK 
{
  "success": true,
  "deleted": true
}