Widget and Form Leads

This document defines the schema and bucket structure for lead integrations with SearchLight. For S3 setup, file format, and access steps see the overview.

Bucket Key Structure

standard-lead/{account-id}/{YYYY-MM-DD}/{filename}.json.gz

Example: standard-lead/pk7f3q9x2m/2026-02-19/leads_bort.json.gz

{account-id} is your internal identifier for the location: the id your own system uses (e.g. pk7f3q9x2m or 48211). Use it as-is and keep it stable for the life of the integration.

Important: the {account-id} value is the Account ID the customer enters in the SearchLight app to turn the integration on. For every location you deliver, share this value with the customer. Leads will not appear in SearchLight until the integration is activated with it.

---

Schema

Field	Type	Required	Description	Example
id	string	required	Must be unique per conversion per account	"12345"
datetime	string (ISO 8601)	required	Timestamp in UTC	"2026-02-19T16:47:48.577Z"
type	string	required	Type of lead conversion ("widget", "chat", or "form")	"widget"
phone_number	string	required	Customer phone number with area code	"123-456-7891"
customer_name	string	required	Full name of the customer	"John Doe"
location_name	string	required	Name of the business location the lead came in for	"Jim's HVAC"
email	string	required	Customer email address	"example@email.com"
content	string	required	Plain text transcript or form content. Newlines allowed	"Need a new furnace\nNo problem"
referrer_url	string	required	Full referrer URL as received	"https://www.google.com/"
landing_page_url	string	required	Full landing page URL as received	"https://exampleplumber.com/?gclid=..."
address	string	optional	Customer address	"123 Main St, Austin, Texas"
zipcode	string	optional	Customer ZIP code. Omit the field when unknown	"12345"
agent	string	optional	Name or identifier of the agent or CSR	"John Doe"
cost	float	optional	Cost of the lead if applicable	27.34