API Reference

The LeadKumo API allows you to submit leads programmatically and integrate with your existing systems.

Base URL

https://your-domain.com/api/v1

Content Type

application/json

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header. 

curl -X POST https://your-domain.com/api/v1/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"leadType": "auto_insurance", ...}'

API Key Format

  • - Minimum 8 characters
  • - Keys are hashed with BCrypt for security
  • - Generate keys from the admin dashboard
  • - Keys can have expiration dates and rate limits

Rate Limiting

API requests are rate limited to ensure fair usage. Rate limits are applied per API key.

Endpoint Limit Window
POST /leads 30 requests 1 minute
POST /leads/batch 30 requests 1 minute
GET /leads/{id} 200 requests 1 minute
POST /ingest/{slug} 60 requests 1 minute

Rate Limit Headers

  • X-RateLimit-Limit: Total requests allowed per period
  • X-RateLimit-Remaining: Requests remaining in current period
  • X-RateLimit-Reset: Unix timestamp when limit resets
  • Retry-After: Seconds to wait (on 429 response)
POST

/leads

Submit a single lead for distribution through the ping/post auction system.

Request Body

{
  "leadType": "auto_insurance",      // Required: Lead type slug
  "sourceId": "partner_123",         // Optional: Traffic source
  "subId": "campaign_456",            // Optional: Sub-source tracking
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "555-123-4567",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",                     // 2-char state code
    "zipCode": "78701"
  },
  "attributes": {                       // Vertical-specific fields
    "vehicleYear": 2022,
    "vehicleMake": "Toyota",
    "currentlyInsured": true
  },
  "consent": {                          // Optional: Compliance data
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "trustedFormCertUrl": "https://cert.trustedform.com/...",
    "consentText": "I agree to be contacted..."
  }
}

Success Response (200 OK)

{
  "success": true,
  "data": {
    "leadId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Sold",
    "price": 25.00,
    "message": "Lead sold to Acme Insurance"
  },
  "error": null
}

Validation Error (422)

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "validationErrors": {
      "Contact.Email": ["Invalid email format"],
      "Contact.State": ["Must be 2 characters"]
    }
  }
}
POST

/leads/batch

Submit multiple leads in a single request. Maximum 50 leads per batch.

Request Body

[
  {
    "leadType": "auto_insurance",
    "contact": { ... },
    "attributes": { ... }
  },
  {
    "leadType": "solar",
    "contact": { ... },
    "attributes": { ... }
  }
]

Response

{
  "success": true,
  "message": "Processed 10 leads, 8 successful",
  "totalProcessed": 10,
  "successCount": 8,
  "failureCount": 2,
  "results": [
    {
      "success": true,
      "data": {
        "leadId": "...",
        "status": "Sold",
        "price": 25.00
      }
    },
    ...
  ]
}
GET

/leads/{id}

Retrieve the current status of a previously submitted lead.

Response

{
  "leadId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Sold",
  "soldPrice": 25.00,
  "soldAt": "2025-01-30T15:30:00Z",
  "createdAt": "2025-01-30T15:29:45Z"
}
POST

/ingest/{slug}

Submit a lead through a legacy field mapping endpoint. Ingest endpoints allow partners to submit leads without changing their field names - only the endpoint URL changes. Field mappings automatically transform legacy field names to LeadKumo standard fields.

Key Benefits

  • - Zero partner changes - Only update the URL, keep existing field names
  • - Flexible formats - Accepts JSON, XML, and form-urlencoded data
  • - Field transformations - Automatic phone formatting, state abbreviation, etc.
  • - Nested JSON support - Map fields like data.contact.first_name
  • - Per-endpoint auth - Unique tokens or standard API keys

Example: Legacy Form Data

// Legacy partner sends their original field names:
{
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "contact_email": "JOHN.DOE@EXAMPLE.COM",
  "phone_number": "(555) 123-4567",
  "state_name": "California",
  "zipcode": "90210-1234"
}

// LeadKumo transforms this to:
{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "john.doe@example.com",  // lowercase
  "Phone": "5551234567",             // digits only
  "State": "CA",                       // abbreviation
  "ZipCode": "90210"                   // normalized
}

Authentication Options

# Option 1: Endpoint-specific token (recommended)
curl -X POST https://your-domain.com/api/v1/ingest/legacy-partner \
  -H "Authorization: Bearer endpoint_token_here" \
  -H "Content-Type: application/json" \
  -d '{"customer_first_name": "John", ...}'

# Option 2: X-Ingest-Token header
curl -X POST https://your-domain.com/api/v1/ingest/legacy-partner \
  -H "X-Ingest-Token: endpoint_token_here" \
  -H "Content-Type: application/json" \
  -d '{"customer_first_name": "John", ...}'

# Option 3: Standard API key
curl -X POST https://your-domain.com/api/v1/ingest/legacy-partner \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_first_name": "John", ...}'

Available Transformations

Transform Input Output
lowercase "JOHN@EXAMPLE.COM" "john@example.com"
phone_digits "(555) 123-4567" "5551234567"
state_abbrev "California" "CA"
zip_normalize "90210-1234" "90210"
boolean "yes" / "1" / "true" "true"
trim " John " "John"

Response Formats

Configure the response format per endpoint: json, xml, or simple (pipe-delimited). 

// JSON response (default)
{
  "success": true,
  "data": {
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Sold",
    "price": 25.00,
    "message": "Lead sold to Acme Insurance"
  }
}

// Simple response
OK|550e8400-e29b-41d4-a716-446655440000|Sold|25.00
GET

/health

Check if the API is operational. No authentication required.

Response

{
  "status": "healthy",
  "timestamp": "2025-01-30T15:30:00Z"
}

Contact Info Model

Field Type Required Description
firstName string No Contact's first name
lastName string No Contact's last name
email string No Valid email address
phone string No Phone number (any format)
address string No Street address
city string No City name
state string No 2-character state code (e.g., "TX")
zipCode string No ZIP code (max 10 chars)

Error Codes

Code HTTP Status Description
VALIDATION_ERROR 422 Request validation failed
INVALID_LEAD_TYPE 400 Lead type slug doesn't exist
LEAD_TYPE_INACTIVE 400 Lead type is disabled
INVALID_ATTRIBUTES 422 Attributes don't match lead type schema
RATE_LIMIT_EXCEEDED 429 Too many requests
INTERNAL_ERROR 500 Unexpected server error

Lead Statuses

Sold

Lead was successfully delivered to a buyer

Pending

Lead is being processed through the ping/post flow

Rejected

No buyers accepted the lead (no bids or all posts failed)

Expired

Lead exceeded its processing time window

Interactive Documentation

Your LeadKumo installation includes interactive API documentation powered by Scalar. Access it at:

https://your-domain.com/scalar/v1