For broadband providers

Bulldog Broadband sends you customers who chose one of your packages at their postcode and agreed to us sharing their details with you. Choose how you receive them: any combination of the three options below. Ask us for setup at [email protected].

1. Email

Each lead goes to a dedicated address of your choice the moment it's submitted. The email contains the customer's details and package, with the same data as JSON in the plain-text part. Replying goes straight to the customer.

2. Webhook (we push to you)

We POST each lead as JSON to your HTTPS endpoint. Return any 2xx status to confirm. If you don't, we retry after 5 minutes, 15 minutes, 1 hour, 3 hours and 12 hours.

Headers:

• X-Bulldog-Event: lead.created
• X-Bulldog-Delivery: unique delivery ID
• X-Bulldog-Timestamp: Unix time
• X-Bulldog-Signature: sha256=<hex>: HMAC-SHA256 of timestamp + "." + raw body using the secret we give you

// PHP example
$expected = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_BULLDOG_TIMESTAMP'] . '.' . file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_BULLDOG_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

3. API (you pull from us)

Send your API key in the header Authorization: Bearer bbk_… (or X-API-Key). You only ever see your own leads.

List leads

GET https://bulldogbroadband.co.uk/api/v1/leads.php?since=2026-10-27T00:00:00Z&status=new&limit=50

Optional filters: since (submitted after), status (new or one of the statuses below), limit (max 200). Results are oldest first.

Get one lead

GET https://bulldogbroadband.co.uk/api/v1/leads.php?reference=BB000123

Update a lead's status

POST https://bulldogbroadband.co.uk/api/v1/leads.php
Content-Type: application/json
{"reference": "BB000123", "status": "sold", "supplier_ref": "ORD-5531", "note": "Install booked 4 Nov"}

Statuses: received, contacted, accepted, sold, rejected, duplicate.

Lead format

{
  "reference": "BB000123",
  "type": "order",
  "submitted_at": "2026-10-27 14:05:11",
  "customer": {"name": "Jane Smith", "email": "[email protected]", "phone": "07700900123",
    "address_line1": "1 High Street", "address_line2": null, "town": "Liskeard",
    "postcode": "PL14 6BT", "uprn": "100040123456", "best_time_to_call": "Evening"},
  "package": {"supplier": "Wildanet", "name": "Full Fibre 500", "monthly_price": 30, "contract_months": 24},
  "addons": [{"name": "Mesh WiFi (2 discs)", "price": 5, "price_type": "monthly"}],
  "line": {"tier": "ultrafast", "max_down": 1000, "max_up": 220},
  "property": "house",
  "current_provider": "BT",
  "consent_share": true,
  "supplier_status": "received",
  "supplier_ref": null
}

Test leads include "test": true and should be ignored.