Postback Endpoint
Send a POST request to create or update a lead. Matches by lead_id first, then email.
POST
/api/postback
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
}'
Order Status Endpoint
Look up an order's fulfillment status by order number — for your funnel or a customer "track my order" page. Authenticated by API key.
GET
/api/order-status?order=ORD-AB12CD
When status is Completed, the response also includes the delivery_date and the document file_location (currently a placeholder URL).
Example — Completed order
curl "http://localhost:3000/api/order-status?order=ORD-AB12CD" \
-H "x-api-key: YOUR_API_KEY"
{
"found": true,
"order_number": "ORD-AB12CD",
"status": "Completed",
"completed": true,
"last_updated": "2026-07-15T18:30:00.000Z",
"delivery_date": "2026-07-15T18:30:00.000Z",
"ein_number": "12-3456789",
"file_location": "https://myeinregistry.com/documents/ORD-AB12CD"
}
Other Endpoints
| Method | Path | Description |
|---|
| GET | /api/order-status | Order status by number. Query: order (API key auth) |
| 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 |