Webhook API Reference

Submit a lead. The endpoint accepts either a single lead object or a JSON array of up to 100 leads in one request. Each lead is deduplicated and routed independently. At least one of email, phone, or first_name is required per lead.

Every field is optional, but at least one of email, phone, or first_name must be present. Unknown fields are ignored. Fields fall into three groups: contact (synced to the HubSpot contact when a routing rule syncs to HubSpot), qualification signals (drive routing & scoring rules), and metadata.

Contact fields → HubSpot contact

{
  "first_name": "Jane",             // string
  "last_name":  "Smith",            // string
  "email":      "jane@email.com",   // string
  "phone":      "+15551234567",     // string
  "mobile_phone": "+15557654321",   // string → HubSpot mobilephone

  // Address
  "contact_address": "123 Main St", // max 300
  "contact_city":    "Austin",      // max 100
  "contact_state":   "TX",          // max 50
  "contact_zip":     "78701",       // max 20
  "country":         "USA",         // max 100

  // Profile / solar enrichment (→ HubSpot contact custom properties)
  "company":          "Acme Co",    // → company
  "job_title":        "Owner",      // → jobtitle
  "website":          "acme.com",   // → website
  "electric_company": "SCE",        // → electric_company

  // Referral attribution (plain text, passed through as-is)
  "referral_code":    "LS-4821",    // → referral_code
  "sales_rep":        "Jane Doe",   // → sales_rep (who referred, NOT owner)

  // Free-text intake body: the customer's message plus any answers with no
  // signal of their own. Rendered as a note on the HubSpot contact.
  "notes": "Wants a call after 5pm.\n\nSurvey answers\n• Roof type: Metal"
}

Two more HubSpot contact properties are derived from the qualification signals below: utilityProvider → utility, billAmount → electric_bill_average, isHomeowner → do_you_own_your_home. The contact's source and lead stage are set by the matched Sync to HubSpot routing rule, not by the webhook.

Qualification signals → routing & scoring

{
  "isHomeowner":      true,         // boolean
  "intentConfirmed":  true,         // boolean
  "utilityProvider":  "SCE",        // string
  "billAmount":       250,          // number
  "billOver100":      true,         // boolean | null
  "creditOver650":    true,         // boolean | null
  "creditRange":      "Good",       // string | null
  "roofCondition":    "Good",       // "Good" | "Workable" | "Poor" | "Unknown" | null
  "interestLevel":    "High",       // "High" | "Medium" | "Low" | null
  "priorSolarConsideration": false, // boolean | null
  "openToTreeTrimming":      true,  // boolean | "yes" | "no" | "not_applicable" (no trees) | null
  "preferredCallbackWindow": "Mornings", // string | null

  // Classification / scoring (usually computed upstream by the CRM)
  "crm_type":       "A",            // "A" | "B"
  "crm_score":      82,             // 0-100
  "classification": "Type A - ...", // string (sets crm_type if crm_type omitted)
  "score":          82,             // 0-100 (alias accepted)
  "scoreBreakdown": { "intent": 30 }// object of numbers
}

Metadata (optional)

{
  "idempotency_key": "unique-id",   // re-submitting the same key refreshes
                                    // the existing lead (cycle) instead of
                                    // inserting a duplicate
  "sourceTag":    "referral",       // one of YOUR source's tags (see Source tags)
  "campaignId":   "camp-123",       "campaignName": "Spring Solar",
  "agentId":      "agent-9",        "agentName":    "Dana R.",
  "qcNotes":      { "agentNotes": "…", "clientNotes": "…" },
  "starRatings":  { "callQuality": 5, "compliance": 5, "tonality": 4 },
  "callRecordingLinks": ["https://…/rec1.mp3"]
}

Success response (201) - single

{
  "id":         "uuid",
  "status":     "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

Cycle-refresh response (200) - single

Returned when an idempotency_key matches an existing lead from the same source. The lead is refreshed and re-routed.

{
  "id":            "uuid",
  "status":        "pending",
  "created_at":    "2024-01-15T10:30:00Z",
  "cycle_refresh": true
}

Send a JSON array (max 100). Each lead is validated and ingested independently - one invalid lead does not reject the others. Every lead consumes one unit of the API key's per-minute rate-limit budget, so a 40-lead batch needs 40 units of remaining capacity or the whole batch is rejected with 429.

Request body - array

[
  { "first_name": "Jane", "email": "jane@email.com" },
  { "first_name": "John", "phone": "+15557654321" },
  { "email": "not-an-email" }        // will fail validation
]

Response - per-item results

Status is 201 when every lead succeeds, 207 when some succeed and some fail, and 422 when every lead fails. The results array preserves request order via index.

HTTP/1.1 207 Multi-Status

{
  "results": [
    { "index": 0, "id": "uuid", "status": "pending",
      "created_at": "2024-01-15T10:30:00Z" },
    { "index": 1, "id": "uuid", "status": "pending",
      "created_at": "2024-01-15T10:30:00Z" },
    { "index": 2, "error": "Validation failed",
      "details": [{ "path": ["email"], "message": "Invalid email address" }] }
  ],
  "summary": { "received": 3, "accepted": 2, "failed": 1 }
}

Submit an appointment. LightSkye auto-assigns it to the next available sales rep based on rank and calendar availability.

Request body

{
  // Contact info
  "contact_first_name": "Jane",           // optional
  "contact_last_name":  "Smith",          // optional
  "contact_email":      "jane@email.com", // optional
  "contact_phone":      "+15551234567",   // optional
  "contact_address":    "123 Main St",    // optional
  "contact_city":       "Austin",         // optional
  "contact_state":      "TX",             // optional - 2-letter code (e.g. TX, CA)
  "contact_zip":        "78701",          // optional - max 10 characters

  // Appointment time (required)
  "requested_date":       "2024-02-01",   // YYYY-MM-DD
  "requested_time_start": "09:00",        // HH:MM (24h)
  "requested_time_end":   "10:00",        // HH:MM (24h)
  "requested_timezone":   "America/Chicago",

  // Optional
  "notes":            "Please call ahead.",
  "lead_id":          "uuid",            // link to an existing lead
  "idempotency_key":  "unique-id",       // prevents duplicate inserts
  "sourceTag":        "referral"         // one of YOUR source's tags (see Source tags)
}

Success response (201)

{
  "id":         "uuid",
  "status":     "pending",    // becomes "assigned" after auto-assignment
  "created_at": "2024-01-15T10:30:00Z"
}

Report something a lead you already sent did on the landing page: pressed "Call me now", asked to be texted other times, requested a callback, or booked on the calendar. The event is stored on the lead and a routing rule decides whether it is pushed to the HubSpot contact. The lead itself is not re-submitted or re-routed. One event per request; the lead must belong to your key's source (otherwise 404).

Request body

{
  // Which lead - one of these is required
  "idempotency_key": "form-8814",   // the key you sent to /api/v1/leads
  "lead_id":         "uuid",        // or the id /api/v1/leads returned

  // The event (required)
  "event_type": "call_me_now",      // call_me_now | text_me_times |
                                    // callback_requested | calendar_booked
  "occurred_at": "2026-09-24T15:04:05Z", // optional, ISO 8601

  // Optional
  "contact": { "first_name": "Jane", "phone": "+15551234567" }, // snapshot, goes into the HubSpot note
  "details": { "slot": "2026-09-25 14:00" }, // flat, max 20 keys
  "notes":   "Free text for the HubSpot note"
}

Success response (201)

{
  "id":             "uuid",
  "lead_id":        "uuid",
  "event_type":     "call_me_now",
  "routing_status": "unassigned",  // routing runs in the background
  "created_at":     "2026-09-24T15:04:06Z"
}

Repeat within 10 minutes (200)

If the same event_type for the same lead already arrived in the last 10 minutes, the request is treated as a repeat: nothing is stored, routed or counted against your rate limit, and you get the existing event back with its current status. For calendar_booked this only happens when details are identical; a booking with different details is a reschedule and is recorded as a new event.

{
  "id":             "uuid",        // the existing event
  "lead_id":        "uuid",
  "event_type":     "call_me_now",
  "routing_status": "assigned",    // its current status
  "created_at":     "2026-09-24T15:04:06Z",
  "deduplicated":   true
}

The full, always-current contract (every limit and error) is served at GET /api/v1/docs with your API key.