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.

Paginated credit ledger (newest first). limit max 200. Includes admin notes and system refunds.

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, 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.

409 link_already_exists if the pair is already linked.

Set distributionRoutingMode: priority | weighted_random | equal_random.

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.

Add funds to a buyer balance.

201 returns 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 deliveries for a calendar day (buyer distribution timezone). Splits the snapshotted daily budget across successful paced deliveries with amount_cents_charged = 0, then deducts from buyer balance.

409 already_settled if that buyer/day was settled. 404 pace_snapshot_not_found if no paced leads were routed that day.

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.