Documentation

Docker Installation (Recommended)

The fastest way to get started is using our automated installer. After completing your purchase, you'll receive a personalized installation script via email:

Manual Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  leadkumo:
    image: ghcr.io/leadkumo/leadkumo:latest
    ports:
      - "80:8080"
    environment:
      - DATABASE_CONNECTION_STRING=Host=db;Database=leadkumo;Username=postgres;Password=secret
      - REDIS_CONNECTION_STRING=redis:6379
    depends_on:
      - db
      - redis

  db:
    image: postgres:16
    environment:
      - POSTGRES_DB=leadkumo
      - POSTGRES_PASSWORD=secret
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

Run with docker compose up -d

Domain Binding Explained

When the installer registers your installation, it creates a record linking your license key to your specific domain. This binding includes:

• - Domain name - The exact domain where LeadKumo is installed
• - Server IP - Your server's public IP address at installation time
• - Version - Which version of LeadKumo was installed
• - Installation date - When the installation was registered

This information is stored securely on our licensing server. Your license cannot be used on a different domain without contacting support.

What Gets Validated

Common Questions

Telnyx Integration (BYOK)

Configure your own Telnyx account for call handling. LeadKumo uses Telnyx for:

• - DID provisioning and management
• - Call control (answer, transfer, hangup)
• - Conference bridging (3-way calls)
• - Call recording with S3 storage
• - Real-time webhooks for call events

Duration-Based Billing

Unlike web leads (accepted/rejected), call leads are billed based on connected duration:

Configuration

Configure CID Lookup under Settings → System → CID Lookup:

Buyers

Buyers are the companies that purchase leads. Each buyer can have multiple campaigns and integrations.

• - Contact information and API key
• - Revenue share percentage
• - Active/inactive status

Campaigns

Campaigns define the business rules for lead buying:

• - Caps: Daily lead and ping limits
• - Operating Hours: When to accept leads (24hr format)
• - Price Floor/Ceiling: Min/max bid amounts
• - Priority: Stack rank boost for competitive bidding
• - Delay: Seconds to wait before accepting

Geographic Targeting

Filter leads by location using state and ZIP code rules. Supports both allowlists and blocklists, with ZIP prefix matching (e.g., "787" matches all ZIPs starting with 787).

• - States: Include specific states (e.g., TX, CA, FL)
• - Excluded States: Block specific states
• - ZIP Codes: Target specific ZIP codes or prefixes
• - Excluded ZIPs: Block specific ZIP codes

Custom Targeting Rules

Define JSON-based rules to filter leads by any attribute. The rule engine supports 15+ operators for numeric, string, array, and boolean comparisons:

{
  "credit_score": { "min": 650 },
  "monthly_electric_bill": { "between": [100, 500] },
  "homeowner": true,
  "coverage_type": { "in": ["full", "liability"] },
  "vehicle_year": { "gte": 2015 }
}

Profile Evaluation

When a lead arrives, the engine evaluates every integration's assigned profile against the lead's geographic data and custom attributes:

• - Both engines: Web leads (PingPost) and call leads use the same profile evaluation logic
• - Fail-open design: Integrations without a profile, or with a disabled profile, pass through without filtering
• - Rejection reasons: Every rejected profile is logged with specific reasons (e.g., "State CA not in targets")
• - Audit trail: ProfileMatched and ProfileRejected events appear on the lead's Activity Timeline

Configuration Options

• - HTTP method (GET, POST, PUT)
• - Content type (JSON, XML, form-urlencoded)
• - Custom headers and authentication
• - Handlebars templates for request body
• - Response parsing (success string, price path, error path)
• - Timeout settings

Live Testing

Test integrations directly from the dashboard before going live. See actual request/response payloads and debug issues.

Available Variables

// Lead Contact Info
{{lead.first_name}}
{{lead.last_name}}
{{lead.email}}
{{lead.phone}}
{{lead.address}}
{{lead.city}}
{{lead.state}}
{{lead.zip_code}}
{{lead.ip_address}}

// Vertical Attributes
{{attributes.vehicle_year}}
{{attributes.monthly_electric_bill}}
{{attributes.credit_score}}

// System Variables
{{ping_id}}
{{timestamp}}
{{source_id}}
{{campaign.custom_field_1}}

JSON Template Example

{
  "request_id": "{{ping_id}}",
  "state": "{{lead.state}}",
  "zip": "{{lead.zip_code}}",
  "vehicle": {
    "year": "{{attributes.vehicle_year}}",
    "make": "{{attributes.vehicle_make}}"
  }
}

XML Template Example

<?xml version="1.0"?>
<LeadRequest>
  <PingID>{{ping_id}}</PingID>
  <Consumer>
    <FirstName>{{lead.first_name}}</FirstName>
    <LastName>{{lead.last_name}}</LastName>
    <Email>{{lead.email}}</Email>
  </Consumer>
</LeadRequest>

Provisioning DIDs

• - Search available numbers by area code or state
• - Provision instantly via Telnyx API
• - Assign to campaigns for automatic routing
• - Copy DID to clipboard for use in ads
• - Track monthly lead volume per DID

DID Configuration

Using DIDs in Advertising

After provisioning, copy the DID from the dashboard and use it in your advertising campaigns (Google Ads call extensions, Facebook call-to-action, print ads, etc.). When callers dial the number, LeadKumo handles the routing automatically.

Features

• - Visual form configuration tied to lead types
• - Reusable DataSets for dropdown options with cascading select support
• - Industry-specific schema presets (Solar, Roofing, Auto Insurance, and more)
• - Custom header and footer HTML
• - TCPA consent text and partner list
• - CSS overrides for custom styling
• - Configurable redirect URL after submission
• - Live preview mode
• - Full FormSchema API for programmatic control over fields, types, validation, and layout

Embedding

Each form gets a unique embed code for your landing pages. Just add the script tag where you want the form to appear:

<script src="https://your-domain.com/forms/your-form-slug/embed.js"></script>

You can also add a data-sub-id attribute for source attribution:

<script src="https://your-domain.com/forms/your-form-slug/embed.js" data-sub-id="landing-page-1"></script>

Forms can also be accessed directly at their URL for previewing or linking:

https://your-domain.com/forms/your-form-slug

Live Demo Sites

See forms in action on our showcase sites, each running LeadKumo-powered lead capture:

• - GetQuoted - Home improvement leads (roofing, solar, windows, and more)
• - MostQuotes - Insurance quote comparison (auto, home, health, Medicare)
• - Affloat - Business lending and financing
• - SelectAccountants - Accounting and bookkeeping services

Creating a DataSet

1. 1
   Navigate to DataSets in the sidebar and click Create DataSet
2. 2
   Enter a Name (slug used in form schemas, e.g., car_makes) and a Display Name
3. 3
   Add your options as a JSON array in the Data field
4. 4
   Optionally link a Parent DataSet for cascading behavior

Option Format

Each dataset stores its options as a JSON array. Every option has a value (submitted with the form) and a label (shown to the user). For cascading selects, include a parent field that matches a value from the parent dataset.

[
  { "value": "toyota", "label": "Toyota" },
  { "value": "honda", "label": "Honda" },
  { "value": "ford", "label": "Ford" }
]

Cascading Example

To create a make/model relationship, create two datasets. The child dataset ("car_models") references the parent dataset ("car_makes") and each option includes a parent value:

[
  { "value": "toyota", "label": "Toyota" },
  { "value": "honda", "label": "Honda" }
]

[
  { "value": "camry", "label": "Camry",
    "parent": "toyota" },
  { "value": "corolla", "label": "Corolla",
    "parent": "toyota" },
  { "value": "civic", "label": "Civic",
    "parent": "honda" }
]

When a user selects "Toyota" in the makes dropdown, the models dropdown automatically shows only Camry and Corolla.

Caching & Performance

When Redis is configured, dataset options are automatically cached to minimize database load on high-traffic forms:

• - Options are cached per dataset with a 5-minute TTL
• - Cache is automatically invalidated when you create, update, or delete a dataset
• - Bulk form loads check cache individually - only missing datasets hit the database
• - Without Redis, every request loads directly from the database - no configuration required

Referencing in Form Schemas

Reference a dataset in your form schema by using the dataset name. The form renderer fetches the options at load time and populates the dropdown automatically.

{
  "name": "vehicle_make",
  "type": "select",
  "label": "Vehicle Make",
  "dataset": "car_makes",
  "required": true
}

Schema Structure

The top-level schema object contains a fields array. Each field object defines a single form input:

{
  "fields": [
    {
      "name": "field_name",
      "type": "text",
      "label": "Display Label",
      "required": true,
      "placeholder": "Hint text",
      "pattern": "regex pattern",
      "minlength": 5,
      "maxlength": 100,
      "options": [
        { "value": "val1", "label": "Option 1" },
        { "value": "val2", "label": "Option 2" }
      ],
      "dataset": "dataset_name"
    }
  ]
}

Field Properties

Field Types

Intelligent Layout

The form renderer automatically groups certain fields for a professional layout. You control the field order in the schema, and the renderer handles responsive column placement:

The state field is always rendered as a dropdown with all 50 US states plus DC, regardless of whether you define options in the schema.

Auto-Generated Field Order

When a form schema is automatically generated from a LeadType definition, fields are sorted into a consistent priority order:

1. 1
   Contact fields first: first_name, last_name, email, phone
2. 2
   Address fields next: address, city, state, zip_code
3. 3
   Vertical-specific fields last: All remaining custom fields for the lead type

You can override this by manually editing the schema and reordering the fields array. The renderer always respects the array order.

LeadType Schema Conversion

When you create a form and select a LeadType that has a JSON Schema definition, the platform automatically converts it to FormSchema format. Here's how property types map:

Form Configuration Properties

Beyond the schema itself, each form has additional configuration properties that control behavior and appearance:

Complete Example

Here's a full FormSchema for an auto insurance lead form with contact fields, address, and vertical-specific questions:

{
  "fields": [
    {
      "name": "first_name",
      "type": "text",
      "label": "First Name",
      "required": true,
      "placeholder": "John"
    },
    {
      "name": "last_name",
      "type": "text",
      "label": "Last Name",
      "required": true,
      "placeholder": "Doe"
    },
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "placeholder": "john@example.com"
    },
    {
      "name": "phone",
      "type": "tel",
      "label": "Phone Number",
      "required": true,
      "placeholder": "(555) 123-4567"
    },
    {
      "name": "address",
      "type": "text",
      "label": "Street Address",
      "required": false
    },
    {
      "name": "city",
      "type": "text",
      "label": "City",
      "required": true
    },
    {
      "name": "state",
      "type": "select",
      "label": "State",
      "required": true
    },
    {
      "name": "zip_code",
      "type": "text",
      "label": "ZIP Code",
      "required": true,
      "pattern": "^\\d{5}(-\\d{4})?$",
      "maxlength": 10
    },
    {
      "name": "vehicle_year",
      "type": "number",
      "label": "Vehicle Year",
      "required": true,
      "placeholder": "2024"
    },
    {
      "name": "vehicle_make",
      "type": "select",
      "label": "Vehicle Make",
      "required": true,
      "dataset": "car_makes"
    },
    {
      "name": "vehicle_model",
      "type": "select",
      "label": "Vehicle Model",
      "required": true,
      "dataset": "car_models"
    },
    {
      "name": "current_insurance",
      "type": "select",
      "label": "Currently Insured?",
      "required": true,
      "options": [
        { "value": "yes", "label": "Yes" },
        { "value": "no", "label": "No" }
      ]
    },
    {
      "name": "accidents_3yr",
      "type": "select",
      "label": "Accidents in Past 3 Years",
      "required": true,
      "options": [
        { "value": "0", "label": "None" },
        { "value": "1", "label": "One" },
        { "value": "2+", "label": "Two or more" }
      ]
    }
  ]
}

This schema produces a fully responsive form with paired name/email/phone fields, an address row, city/state/zip grouping, and vertical-specific dropdowns powered by DataSets.

Individual Returns

Process single returns directly from the Sales page or Sale Details page:

1. 1
   Navigate to Sales and find the transaction
2. 2
   Click the return action button or open Sale Details
3. 3
   Enter return reason and optional return code
4. 4
   Confirm - the sale status updates to "Returned"

Bulk Returns (CSV Upload)

Process multiple returns at once using buyer-provided return files:

# Example CSV format
transaction_id,reason,code,date
a1b2c3d4-e5f6-7890-abcd-ef1234567890,Bad contact info,INVALID_CONTACT,2024-01-15
b2c3d4e5-f6a7-8901-bcde-f12345678901,Duplicate lead,DUPLICATE,
c3d4e5f6-a7b8-9012-cdef-123456789012,Customer canceled,,

Validation & Results

The system validates each return and provides detailed feedback:

Return Statistics

The Sales page displays key return metrics:

Buyer Return Reports

Track return rates by buyer to identify quality issues. High return rates may indicate targeting problems or integration issues that need attention. The Reports section includes return rate breakdowns per buyer and campaign.

Creating an Ingest Endpoint

Navigate to Management → Ingest Endpoints → New Endpoint. The wizard guides you through three steps:

Field Mapping Types

Available Transformations

Testing Transformations

Use the Test page to validate your mappings before going live:

• - Paste sample JSON from your partner
• - See field-by-field transformation trace
• - View final output that would be created
• - Identify missing required fields

Authentication Options

Dot Notation for Nested JSON

Source fields support dot notation to extract values from nested JSON structures:

// Partner sends nested data:
{
  "data": {
    "contact": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "email": "john@example.com"
  }
}

// Field mappings:
data.contact.first_name → FirstName
data.contact.last_name  → LastName
data.email              → Email

Email Delivery Setup

Configure SMTP settings once in Settings → System → SMTP, then create reusable email templates.

SMS Delivery Setup

Configure your SMS provider in Settings → System → SMS. Supports Telnyx (recommended) and Twilio.

Template Variables

Use Handlebars syntax to insert lead data into your templates. All standard lead fields are available:

New lead received!

Name: {{FirstName}} {{LastName}}
Email: {{Email}}
Phone: {{Phone}}
State: {{State}}
Source: {{SourceName}}

{{#if Custom1}}Notes: {{Custom1}}{{/if}}

Integration Configuration

When creating or editing an integration, select the delivery method and assign a template:

Additional Event Types

Database Backups

• - Automated PostgreSQL backups with pg_dump
• - Gzip compression for storage efficiency
• - AES-256 encryption for sensitive data
• - Optional SFTP upload to remote server
• - Configurable retention period
• - Backup history and status tracking

Data Cleanup

• - Configurable lead expiry (default: 365 days)
• - Ping/post expiry for unsold leads (default: 120 days)
• - Grace period before permanent deletion
• - Audit log retention settings
• - Sales records are never deleted (permanent)

Job Management

• - View scheduled job execution history
• - Manually trigger backup or cleanup jobs
• - Monitor progress of running jobs
• - View job results and error messages

Redis Cache

• - Connection configuration and testing
• - Cache statistics monitoring
• - Used for campaign caps, ping queuing, and form dataset options
• - Optional - all features work without Redis, loading directly from the database