Leads

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

string

required

Phone number (E.164 or 10-digit). Auto-normalized.

string

Full name

string

First name

string

Last name

string

Email address

string

Company or employer

string

Free-text notes

string

Lead source label (e.g., application, collection)

string

Your internal ID for deduplication

string

Property address

boolean

default:"false"

Start the default sequence immediately

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": "john@example.com",
    "source": "application",
    "external_id": "app_98765",
    "auto_sequence": true,
    "notes": "Stalled at document upload step"
  }'

const res = await fetch(`https://api.recoverbiz.com/v1/accounts/${accountId}/leads`, {
  method: 'POST',
  headers: {
    'X-Partner-Key': 'pk_live_abc123def456...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+14155551234',
    name: 'John Doe',
    email: 'john@example.com',
    source: 'application',
    external_id: 'app_98765',
    auto_sequence: true,
    notes: 'Stalled at document upload step',
  }),
});
const lead = await res.json();

requests.post(f'{BASE_URL}/accounts/{account_id}/leads', headers=headers, json={
    'phone': '+14155551234',
    'name': 'John Doe',
    'email': 'john@example.com',
    '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": "john@example.com",
    "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

integer

default:"50"

Max results (1-250)

integer

default:"0"

Pagination offset

string

Filter: new, contacted, qualified, converted, lost

string

Search name, email, phone

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": "john@example.com",
      "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": "john@example.com",
  "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": "john@example.com" }
    ]
  },
  "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
}

Core API

Features

Platform

Import a Lead

Bulk Import

List Leads

Get Lead

Update Lead

Delete Lead

​Import a Lead

​Bulk Import

​List Leads

​Get Lead

​Update Lead

​Delete Lead

Import a Lead

Bulk Import

List Leads

Get Lead

Update Lead

Delete Lead