Leads

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.

string

Filter by lead status. Accepted values: "new", "contacted", "qualified", "converted".

string

Filter by the channel that captured the lead. Accepted values: "call", "sms", "form", "facebook", "google".

string

Field to sort results by. Default: "created_at".

integer

Number of results per page. Default: 20.

curl "https://api.boltcall.org/v1/leads?status=new&source=call&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

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();

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()

Response

{
  "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 }
}

Show Response fields

string

Unique lead identifier.

string

Lead’s full name.

string

Phone number in E.164 format.

string

Email address.

string

Current pipeline status: "new", "contacted", "qualified", or "converted".

string

Channel that captured the lead.

integer

AI-generated lead score from 0–100 based on engagement signals.

string[]

Tags applied to the lead for segmentation.

string

ISO 8601 timestamp when the lead was created.

Create a lead

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

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

string

required

Full name of the lead.

string

Phone number in E.164 format (e.g. "+15551234567").

string

Email address of the lead.

string

Label describing where the lead came from (e.g. "crm-import", "referral").

string[]

Array of tags to apply for segmentation (e.g. ["high-intent", "hvac-repair"]).

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"]
  }'

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();

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()

Response

{
  "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

string

required

The ID of the lead to update.

Body — pass any subset of the fields below:

string

Updated full name.

string

Updated phone number (E.164).

string

Updated email address.

string

Updated pipeline status: "new", "contacted", "qualified", or "converted".

string[]

Replaces the existing tag list entirely.

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"]
  }'

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();

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()

Response

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

Subscribe to the new_lead webhook event 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.

Overview

Endpoints

List leads

Create a lead

Update a lead

​List leads

​Create a lead

​Update a lead

List leads

Create a lead

Update a lead