Supplier API Reference

This reference is for approved suppliers submitting leads to Premium Qualified Leads.

Admin supplier management endpoints exist internally but are not public partner documentation.

Endpoints

Method	Path	Purpose	Auth
POST	/api/v1/ingest	Submit one lead for asynchronous processing.	x-api-key supplier key
GET	/api/v1/supplier/stats?days=30	View recent submission and routing stats for the authenticated supplier.	x-api-key supplier key

Lead submission behavior

• Field mapping may be applied per supplier before the lead is parsed.

• The response confirms acceptance into processing, not final buyer delivery.

• Accepted leads are processed asynchronously.

• Supplier requests are not blocked by downstream routing or delivery work.

• If a supplier callback webhook is configured, processing errors may be sent back as a callback event.

Example request

POST /api/v1/ingest
x-api-key: YOUR_SUPPLIER_API_KEY
Content-Type: application/json

{
"external_id": "lead-123",
"full_name": "Jane Example",
"email": "jane@example.com",
"phone": "+15555550123",
"business_name": "Example Services LLC",
"state": "FL",
"debt_amount": "100000",
"source": "approved-campaign",
"consent_timestamp": "2026-01-01T12:00:00Z",
"source_form_url": "https://example.com/form"
}

Accepted response

{
"accepted": true,
"lead_id": "lead-123",
"score": 78,
"processingTime": 42
}

Rejected response

{
"accepted": false,
"reason": "email or phone required; name required",
"processingTime": 18
}

Supplier stats

GET /api/v1/supplier/stats?days=30
x-api-key: YOUR_SUPPLIER_API_KEY

Example response:

{
"days": 30,
"supplierKey": "supplier-one",
"totals": {
"submitted": 120,
"routed": 94,
"rejected": 8,
"pending": 18,
"acceptanceRate": 78,
"avgScore": 71
},
"byStatus": {
"Calendar Assigned": 40,
"Lead Sale": 54
}
}