Postback Endpoint

Send a POST request to create or update a lead. Matches by lead_id first, then email.

Headers

Content-Type: application/json
x-api-key: YOUR_API_KEY   (optional when API_KEY=changeme)

Body Fields

Field	Type	Description
lead_id	string	Optional. Reuse existing lead UUID to update it.
email	string	Used for dedup if lead_id not provided.
first_name	string
last_name	string
phone	string
company	string
stage	string	One of the pipeline stages below.
source	string	e.g. "google", "facebook"
domain	string	Landing page domain
campaign	string	Campaign name or ID
utm_source	string
utm_medium	string
utm_campaign	string
utm_term	string
utm_content	string
referrer	string	Full referrer URL
ip_address	string
user_agent	string
browser	string	e.g. "Chrome 124"
device_type	string	"desktop" / "mobile" / "tablet"
form_completion_percent	number	0–100
form_fields_completed	number
form_fields_total	number
custom_data	object	Any extra key/value pairs
force_stage	boolean	true = allow going backwards in stage

Pipeline Stages (in order)

Example — Form Started

curl -X POST http://localhost:3000/api/postback \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "stage": "Form Started",
    "source": "google",
    "domain": "myeinregistry.com",
    "campaign": "llc-spring-2026",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "llc-spring-2026",
    "ip_address": "192.168.1.1",
    "browser": "Chrome 124",
    "device_type": "desktop",
    "form_completion_percent": 10,
    "form_fields_total": 12
  }'

Example — Application Submitted

curl -X POST http://localhost:3000/api/postback \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "stage": "Application Submitted",
    "form_completion_percent": 100,
    "form_fields_completed": 12,
    "form_fields_total": 12
  }'

Other Endpoints

Method	Path	Description
GET	/api/leads	List leads. Query: stage, search, source, campaign, from, to, page, limit
GET	/api/leads/:id	Get single lead + stage history
PUT	/api/leads/:id/stage	Manually update stage. Body: {"stage": "Paid"}
DELETE	/api/leads/:id	Delete lead
GET	/api/analytics	Dashboard analytics