Optimize LeadRoute

Liveness check. Returns { "ok": true }.

Accept a lead for a campaign. Body must be a JSON object (not an array).

Success (200) includes leadId, status (delivered, quarantine, or failed), and charge fields when applicable.

Webhook configuration

Copy the ingest URL from the dashboard campaign row — it includes campaignId and token. No API key or session cookie on ingest.

HTTP request

POST /api/webhooks/campaigns/1?token=YOUR_CAMPAIGN_TOKEN HTTP/1.1
Host: $HOST
Content-Type: application/json
Idempotency-Key: lead-abc-123

{
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "5551234567",
  "email": "jane@example.com",
  "source": "fb",
  "homeowner": "Yes",
  "monthlyElectricBill": "185",
  "utilityBillUpload": "https://example.com/bill.pdf"
}

Request body (JSON only)

Use this in webhook tools that have a separate JSON body field.

{
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "5551234567",
  "email": "jane@example.com",
  "source": "fb",
  "homeowner": "Yes",
  "monthlyElectricBill": "185",
  "utilityBillUpload": "https://example.com/bill.pdf"
}

Example success response

{
  "leadId": 42,
  "status": "delivered",
  "distributionId": 3,
  "pricingMode": "pay_per_lead",
  "amountCentsCharged": 100,
  "amountUsdCharged": 1
}

curl -X POST "$BASE/api/webhooks/campaigns/1?token=YOUR_CAMPAIGN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-abc-123" \
  -d '{"firstName":"Jane","lastName":"Doe","phone":"5551234567","email":"jane@example.com","source":"fb"}'

200: { "ok": true, "username": "…" } and sets session cookie. 401: invalid_credentials.

Clears the session cookie. Returns { "ok": true }.

200: { "ok": true, "username": "…" }. 401: not_authenticated.

Full snapshot for the dashboard: accounts, campaigns (with ingest URLs), campaignCustomFields, buyers, distributions, links, leads, etc.

Daily aggregates for the analytics tab. days defaults to 30 when omitted or invalid. Calendar days use server ANALYTICS_TZ (default America/Denver). Response includes reportingTimezone, timezoneNote, and todaySummary.date in that zone.

Also returns todaySummary, profitTotals, profitPerDay, and profitByCampaign. Leads sold (deliveredCount) is successful first-time buyer deliveries (is_repush = 0, includes revenue share). Revenue is the sum of amount_cents_charged on those deliveries. Amount spent (costCents) is the sum of each lead’s campaign lead cost (acquisition_cost_cents, or current lead_cost_cents if unset). Profit is revenue minus amount spent.

Buyer profile for the dashboard card: buyer (includes billingType, totalFundedCents, totalChargedCents), distributions, credits, charges (successful deliveries with amount charged, including leadId), and paceSettlements.

Optional query: creditsLimit, chargesLimit, paceLimit.

Paginated credit ledger (newest first). limit max 200. Each row includes creditKind (funding | refund).

201 returns account with id, name, timezone. Optional — buyers and campaigns auto-use a default account when accountId is omitted.

201 returns buyer with id, billingType, balanceCents, balanceUsd.

201 returns campaign with auto-generated webhookToken and ingestUrl.

curl -X POST "$BASE/api/admin/campaigns" \
  -H "Content-Type: application/json" \
  -H "x-admin-key: YOUR_ADMIN_API_KEY" \
  -d '{"name":"Summer promo","isActive":true}'

Clone campaign configuration. Does not copy leads or delivery history.

201 returns new campaign with fresh webhookToken and ingestUrl.

Add an optional (or required) custom ingest field to a campaign. Manage from dashboard Campaigns → Fields.

409 field_key_exists if the key is already on the campaign.

Update label, dataType, isRequired, and/or sortOrder. fieldKey is immutable after create.

Remove a custom field definition. Past lead payloads in payload_json are unchanged.

Add a quarantine filter rule. Manage from dashboard Campaigns → Filters. On ingest, if any active rule matches a top-level payload field, the lead is stored as quarantine with reason filtered_by_campaign_rule and is not routed to a buyer.

Matching is case-insensitive. First matching active rule wins (by sort order).

Update name, fieldKey, operator, matchValue, isActive, and/or sortOrder. Dashboard Filters → Edit uses this.

Remove a filter rule. Past quarantined leads are unchanged.

409 link_already_exists if the pair is already linked.

Partial update. Body: billingType — prepaid, at_cost, or revenue_share.

prepaid — distribution price / paced wallet. at_cost — charge campaign lead cost at delivery; balance must cover it. revenue_share — no wallet charge; credits API returns 409 buyer_credits_not_allowed.

Set distributionRoutingMode (priority | weighted_random | equal_random) and/or leadCostUsd (whole dollars, 0 or more). Lead cost changes apply to future deliveries only.

Update sortOrder and/or weight (integer ≥ 1) on a campaign↔distribution link.

Partial update. Any of: name, outboundWebhookUrl, pricingMode, paceDays, pricePerLeadUsd, pricePerLeadCents, weekdaysOnly, windowStartMinutes, windowEndMinutes, dailyCap (send null to clear), timezone, isActive.

Switching to paced_wallet clears fixed price. Switching to pay_per_lead requires a price.

Removes the campaign, its routing links, custom fields, and all leads for that campaign.

Removes buyer, credit history, and distributions. Fails with buyer_has_balance if balance > 0.

Removes distribution and campaign links. Delivery history for past leads remains on lead records.

Unlinks a distribution from a campaign. Does not delete the campaign or the distribution — only the routing link row.

404 link_not_found if the link id does not exist.

Add to a buyer balance. Not allowed for revenue_share buyers (409 buyer_credits_not_allowed).

201 returns creditKind, updated balanceCents / balanceUsd.

curl -X POST "$BASE/api/admin/buyers/1/credits" \
  -H "Content-Type: application/json" \
  -H "x-admin-key: YOUR_ADMIN_API_KEY" \
  -d '{"amountUsd":500,"note":"Monthly top-up"}'

Settle paced wallet charges for a calendar day (buyer distribution timezone). Deducts the daily budget (floor(balance ÷ paceDays) from the day’s snapshot) even when there were 0 deliveries. If successful paced deliveries exist with amount_cents_charged = 0, the same budget is split across them. Creates a snapshot at settle time if none exists yet for that date.

409 already_settled if that buyer/day was settled. Buyers with $0 balance are skipped for routing and settle with $0 charged.

Optional auto-run: set env SETTLE_PACED_CRON (e.g. 5 0 * * *) and SETTLE_PACED_TZ (default America/Denver). The server settles yesterday in that timezone when the cron fires.

Paginated lead list for the dashboard Leads tab.

Returns { leads, page, limit, total, totalPages }. Each lead includes id, campaignId, campaignName, status, quarantineReason, phonePreview, createdAt, and when routed/delivered/failed with a chosen distribution: buyerId, buyerName, chosenDistributionId, distributionName.

Full lead detail for the dashboard View dialog: ingest payload (all fields), ingestResponse, campaign/distribution/buyer names, and deliveries.

Re-run routing for quarantined leads (no_eligible_distribution, insufficient_balance_before_delivery).

Optional body: { "distributionId": 123 } to force a specific distribution.

Resend the stored ingest payload to the original buyer webhook (chosen_distribution_id). No buyer balance charge. Allowed when lead status is delivered or failed.

Appends a delivery row with is_repush (excluded from daily cap and revenue analytics). Optional body { "distributionId": 123 } must match the original distribution.