Authentication
All API requests use Bearer token authentication. Your API token is issued when your application is approved. Include it in every request:
Authorization: Bearer dl_live_xxxxxxxxxxxxxxxxxxxx
Tokens are environment-scoped: dl_test_ for sandbox, dl_live_ for production. Test tokens return synthetic lead data and do not trigger billing.
Buyer Webhook — Receiving Leads
As a buyer, you provide an HTTPS endpoint that we POST lead data to when you win an auction. Your endpoint must:
- Accept HTTPS POST requests
- Return HTTP 200 within 10 seconds
- Return a JSON body with
"status": "accepted" or "status": "rejected"
We send the following headers on every buyer webhook delivery:
POST https://your-crm.com/leads/inbound
Content-Type: application/json
X-DreamyLeads-Signature: sha256=xxxxxxxx
X-DreamyLeads-LeadId: ld_8f2a91bc
X-DreamyLeads-Version: 2026-04
Verifying the Signature
The X-DreamyLeads-Signature header contains an HMAC-SHA256 signature of the raw request body using your webhook secret (separate from your API token). Always verify this before processing:
// Node.js
const crypto = require('crypto');
const sig = req.headers['x-dreamyleads-signature'];
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.DL_WEBHOOK_SECRET)
.update(req.rawBody)
.digest('hex');
if (sig !== expected) return res.status(401).end();
Publisher Endpoint — Submitting Leads
As a publisher, you POST leads to our inbound endpoint. The ping-tree responds in real time with an accept or reject decision and a bid price.
POST https://api.dreamyleads.com/webhook/lead
Authorization: Bearer dl_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Payload Schema
All fields marked * are required. Vertical-specific fields are marked with their vertical.
{
"vertical": "insurance", // * insurance | mortgage | solar | debt
"first_name": "Maria", // *
"last_name": "G.", // *
"email": "m@example.com", // *
"phone": "+18135550100", // * E.164 format
"zip": "33601", // * 5-digit US ZIP
"tcpa_timestamp": "2026-04-27T09:14:22Z", // * ISO 8601
"tcpa_text": "By submitting...", // * verbatim consent
"tcpa_url": "https://...", // * page URL
// Insurance-specific
"coverage_type": "auto",
"vehicle_year": 2021,
"homeowner": true,
// Mortgage-specific
"loan_purpose": "purchase",
"loan_amount": 385000,
"credit_range": "good",
// Solar-specific
"monthly_electric_bill": 285,
"roof_type": "shingle",
// Debt-specific
"debt_amount": "15000–25000",
"debt_type": "credit_card"
}
Response Codes
| HTTP Status | Meaning | Action |
|---|
200 accepted | Lead accepted, bid placed | Record lead_id for tracking |
200 rejected | Lead rejected (below score threshold or filter mismatch) | No charge; log and continue |
400 | Malformed request (missing required fields) | Fix payload; do not retry |
401 | Invalid or missing Bearer token | Check token; do not retry |
422 | TCPA fields missing or invalid | Fix consent fields; do not retry |
429 | Rate limit exceeded | Back off 60s; retry |
5xx | Server error | Retry with exponential backoff |
Error Handling & Retries
For 5xx responses, retry with exponential backoff: 1s, 2s, 4s, 8s, then abandon. For 429 responses, respect the Retry-After header. Never retry 4xx responses — they indicate a fixable problem with your request, not a transient server issue.
Code Samples
cURL
curl -X POST https://api.dreamyleads.com/webhook/lead \
-H "Authorization: Bearer dl_live_xxxx" \
-H "Content-Type: application/json" \
-d '{"vertical":"insurance","first_name":"Maria","last_name":"G.","email":"m@example.com","phone":"+18135550100","zip":"33601","tcpa_timestamp":"2026-04-27T09:14:22Z","tcpa_text":"By submitting...","tcpa_url":"https://seo.example.com/page"}'
Node.js
const res = await fetch('https://api.dreamyleads.com/webhook/lead', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.DL_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
vertical: 'insurance',
first_name: 'Maria', last_name: 'G.',
email: 'm@example.com', phone: '+18135550100', zip: '33601',
tcpa_timestamp: new Date().toISOString(),
tcpa_text: 'By submitting this form you consent...',
tcpa_url: window.location.href,
}),
});
const data = await res.json(); // { status: 'accepted', bid_amount: 18.50, lead_id: 'ld_...' }
Python
import requests, os
resp = requests.post(
'https://api.dreamyleads.com/webhook/lead',
headers={'Authorization': f"Bearer {os.environ['DL_API_KEY']}"},
json={
'vertical': 'insurance',
'first_name': 'Maria', 'last_name': 'G.',
'email': 'm@example.com', 'phone': '+18135550100', 'zip': '33601',
'tcpa_timestamp': '2026-04-27T09:14:22Z',
'tcpa_text': 'By submitting this form you consent...',
'tcpa_url': 'https://seo.example.com/page',
},
timeout=15
)
print(resp.json()) # {'status': 'accepted', 'bid_amount': 18.5, 'lead_id': 'ld_...'}
Need help integrating?
Email dreamyleads@gmail.com with your lead_id and the response you received. We respond within 24 hours on business days.