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

# Leads

> List, create, and update leads captured from calls, SMS, forms, and ad platforms.

Leads represent contacts that have engaged with your business through any channel — inbound calls, SMS, web forms, Facebook Lead Ads, or Google Ads. You can also create leads manually via the API to sync contacts from external systems.

## List leads

Returns a paginated list of leads. Filter by status or source to segment your pipeline.

<ParamField query="status" type="string">
  Filter by lead status. Accepted values: `"new"`, `"contacted"`, `"qualified"`, `"converted"`.
</ParamField>

<ParamField query="source" type="string">
  Filter by the channel that captured the lead. Accepted values: `"call"`, `"sms"`, `"form"`, `"facebook"`, `"google"`.
</ParamField>

<ParamField query="sort" type="string">
  Field to sort results by. Default: `"created_at"`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page. Default: `20`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.boltcall.org/v1/leads?status=new&source=call&limit=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ status: 'new', source: 'call', limit: '20' });
  const response = await fetch(`https://api.boltcall.org/v1/leads?${params}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  });
  const { data, meta } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.boltcall.org/v1/leads',
      params={'status': 'new', 'source': 'call', 'limit': 20},
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  )
  result = response.json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "lead_001",
      "name": "Jane Smith",
      "phone": "+15551234567",
      "email": "jane@example.com",
      "status": "new",
      "source": "call",
      "score": 85,
      "tags": ["high-intent", "dental-cleaning"],
      "created_at": "2025-03-20T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 42 }
}
```

<Expandable title="Response fields">
  <ResponseField name="id" type="string">
    Unique lead identifier.
  </ResponseField>

  <ResponseField name="name" type="string">
    Lead's full name.
  </ResponseField>

  <ResponseField name="phone" type="string">
    Phone number in E.164 format.
  </ResponseField>

  <ResponseField name="email" type="string">
    Email address.
  </ResponseField>

  <ResponseField name="status" type="string">
    Current pipeline status: `"new"`, `"contacted"`, `"qualified"`, or `"converted"`.
  </ResponseField>

  <ResponseField name="source" type="string">
    Channel that captured the lead.
  </ResponseField>

  <ResponseField name="score" type="integer">
    AI-generated lead score from 0–100 based on engagement signals.
  </ResponseField>

  <ResponseField name="tags" type="string[]">
    Tags applied to the lead for segmentation.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the lead was created.
  </ResponseField>
</Expandable>

***

## Create a lead

Creates a lead manually. Useful for syncing contacts from a CRM or external form.

<Note>
  At least one of `phone` or `email` is recommended. A lead with neither cannot be contacted by an agent.
</Note>

<ParamField body="name" type="string" required>
  Full name of the lead.
</ParamField>

<ParamField body="phone" type="string">
  Phone number in E.164 format (e.g. `"+15551234567"`).
</ParamField>

<ParamField body="email" type="string">
  Email address of the lead.
</ParamField>

<ParamField body="source" type="string">
  Label describing where the lead came from (e.g. `"crm-import"`, `"referral"`).
</ParamField>

<ParamField body="tags" type="string[]">
  Array of tags to apply for segmentation (e.g. `["high-intent", "hvac-repair"]`).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.boltcall.org/v1/leads \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Doe",
      "phone": "+15559876543",
      "email": "john@example.com",
      "source": "crm-import",
      "tags": ["hvac-repair"]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'John Doe',
      phone: '+15559876543',
      email: 'john@example.com',
      source: 'crm-import',
      tags: ['hvac-repair'],
    }),
  });
  const lead = await response.json();
  ```

  ```python Python theme={null}
  import requests

  lead = requests.post(
      'https://api.boltcall.org/v1/leads',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'name': 'John Doe',
          'phone': '+15559876543',
          'email': 'john@example.com',
          'source': 'crm-import',
          'tags': ['hvac-repair'],
      },
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "lead_002",
  "name": "John Doe",
  "status": "new",
  "created_at": "2025-03-20T11:30:00Z"
}
```

***

## Update a lead

Updates one or more fields on an existing lead. Only the fields you include are changed.

**Path parameter**

<ParamField path="lead_id" type="string" required>
  The ID of the lead to update.
</ParamField>

**Body** — pass any subset of the fields below:

<ParamField body="name" type="string">
  Updated full name.
</ParamField>

<ParamField body="phone" type="string">
  Updated phone number (E.164).
</ParamField>

<ParamField body="email" type="string">
  Updated email address.
</ParamField>

<ParamField body="status" type="string">
  Updated pipeline status: `"new"`, `"contacted"`, `"qualified"`, or `"converted"`.
</ParamField>

<ParamField body="tags" type="string[]">
  Replaces the existing tag list entirely.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.boltcall.org/v1/leads/lead_001 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "qualified",
      "tags": ["high-intent", "dental-cleaning", "callback-requested"]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/leads/lead_001', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      status: 'qualified',
      tags: ['high-intent', 'dental-cleaning', 'callback-requested'],
    }),
  });
  const updated = await response.json();
  ```

  ```python Python theme={null}
  import requests

  updated = requests.patch(
      'https://api.boltcall.org/v1/leads/lead_001',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'status': 'qualified',
          'tags': ['high-intent', 'dental-cleaning', 'callback-requested'],
      },
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "lead_001",
  "name": "Jane Smith",
  "status": "qualified",
  "tags": ["high-intent", "dental-cleaning", "callback-requested"],
  "updated_at": "2025-03-21T09:00:00Z"
}
```

<Tip>
  Subscribe to the `new_lead` [webhook event](/api/webhooks) to receive instant notifications when Boltcall captures a lead from a call or form, so you can trigger follow-up automation without polling this endpoint.
</Tip>