> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoverbiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leads

> Import and manage leads across sub-accounts.

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`

<ParamField body="phone" type="string" required>
  Phone number (E.164 or 10-digit). Auto-normalized.
</ParamField>

<ParamField body="name" type="string">
  Full name
</ParamField>

<ParamField body="first_name" type="string">
  First name
</ParamField>

<ParamField body="last_name" type="string">
  Last name
</ParamField>

<ParamField body="email" type="string">
  Email address
</ParamField>

<ParamField body="company" type="string">
  Company or employer
</ParamField>

<ParamField body="notes" type="string">
  Free-text notes
</ParamField>

<ParamField body="source" type="string">
  Lead source label (e.g., `application`, `collection`)
</ParamField>

<ParamField body="external_id" type="string">
  Your internal ID for deduplication
</ParamField>

<ParamField body="property_address" type="string">
  Property address
</ParamField>

<ParamField body="auto_sequence" type="boolean" default="false">
  Start the default sequence immediately
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs stored on the lead
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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'
  })
  ```
</CodeGroup>

**Response: `201 Created`**

```json theme={null}
{
  "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"
  }
}
```

<Note>
  **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"`.
</Note>

## Bulk Import

`POST /accounts/:id/leads/bulk`

Import up to 1,000 leads in a single request.

```bash theme={null}
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`**

```json theme={null}
{
  "success": true,
  "imported": 2,
  "updated": 0,
  "skipped": 0,
  "errors": []
}
```

## List Leads

`GET /accounts/:id/leads`

<ParamField query="limit" type="integer" default="50">
  Max results (1-250)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset
</ParamField>

<ParamField query="status" type="string">
  Filter: `new`, `contacted`, `qualified`, `converted`, `lost`
</ParamField>

<ParamField query="search" type="string">
  Search name, email, phone
</ParamField>

<ParamField query="source" type="string">
  Filter by source label
</ParamField>

```bash theme={null}
curl https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads?status=qualified&limit=20 \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
curl -X DELETE https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/leads/+14155551234 \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "success": true,
  "deleted": true
}
```