Lead delivery API
Last updated 18 November 2026
Leads can reach your systems three ways. Use whichever fits, or several at once — each destination is independent and each is retried separately.
- Push — we POST each lead to a destination you configure.
- Pull — your system polls
GET /api/v1/leads. - Email — the default, with no setup at all.
Destinations
Add these under Portal → Lead delivery. Each destination can be filtered by technology and minimum speed, so you can route fibre gigabit enquiries to one team and LTE to another.
| Type | What it does |
|---|---|
webhook | POST each lead as JSON to your own endpoint, signed with HMAC-SHA256 so you can verify it came from us. |
zapier | Paste a Zapier "Catch Hook" or Make "Custom webhook" URL and route leads into any of their thousands of apps. |
slack | Post each lead into a Slack channel via an incoming webhook. |
hubspot | Create a HubSpot contact for each lead using a private app token. |
pipedrive | Create a Pipedrive person and an attached lead. |
salesforce | Submit each lead through your Salesforce Web-to-Lead endpoint. No OAuth setup required. |
google_sheets | Append each lead as a row. Deploy the Apps Script snippet from our docs and paste its web app URL here. |
email | Send each lead to one or more inboxes. Reply goes straight to the customer. |
Webhooks
We POST application/json to your endpoint. The endpoint must behttps, must not resolve to a private address, and should answer with any 2xx status as soon as it has accepted the lead — do your processing afterwards, not before responding.
Headers
| Header | Value |
|---|---|
X-BBF-Event | lead.created or lead.test |
X-BBF-Delivery | Unique id for this delivery attempt chain |
X-BBF-Signature | t=<unix>,v1=<hex hmac> |
Payload
{
"version": "1",
"event": "lead.created",
"id": "7c3f1b2a-...",
"created_at": "2026-11-18T09:14:22.118Z",
"provider": { "id": "...", "name": "Lumio Fibre" },
"customer": {
"full_name": "Thandi Mokoena",
"email": "thandi@example.com",
"phone": "+27821234567",
"preferred_time": "Mornings (8am–12pm)"
},
"location": {
"address": "12 Rivonia Road, Sandton, Johannesburg",
"lat": -26.1076,
"lng": 28.0567,
"suburb": "Sandton",
"city": "Johannesburg",
"province": "Gauteng",
"postcode": "2196"
},
"package": {
"id": "...",
"name": "Lumio 200",
"technology": "fibre",
"download_mbps": 200,
"upload_mbps": 200,
"price_cents": 89900,
"currency": "ZAR"
},
"notes": "Please call after 5pm",
"consent": true,
"source": { "site": "yourbroadbandfinder.com", "search_id": "..." }
}version is the contract. We may add fields without changing it; we will not change the meaning of an existing field or remove one without publishing a new version and giving notice.
Verifying the signature
The signed string is `${timestamp}.${rawBody}`. Compute an HMAC-SHA256 of it with your signing secret and compare, in constant time, with the v1 value. Reject anything with a timestamp older than five minutes — that is what stops a captured request being replayed.
Node
import crypto from 'node:crypto';
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(',').map((p) => p.split('=').map((s) => s.trim())),
);
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
if (!Number.isFinite(Number(parts.t)) || age > 300) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(parts.v1 ?? '', 'utf8');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}PHP
function bbf_verify(string $rawBody, string $header, string $secret): bool {
parse_str(str_replace(',', '&', $header), $parts);
if (!isset($parts['t'], $parts['v1'])) return false;
if (abs(time() - (int) $parts['t']) > 300) return false;
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $parts['v1']);
}Verify against the raw request body, before any JSON parsing. Re-serialising the payload changes the bytes and the signature will never match.
Retries
A non-2xx response, a connection error, or no answer within 10 seconds counts as a failure. We retry up to 6 times with exponential backoff — roughly 1 minute, 5 minutes, 25 minutes, 2 hours, then 10 hours. Every attempt is recorded with its status code and error, visible under Portal → Lead delivery.
Deliveries are at-least-once, so make your handler idempotent: key on the lead id and ignore one you have already stored.
REST API
Base URL https://yourbroadbandfinder.com/api/v1. Authenticate with a key generated under Portal → API keys:
Authorization: Bearer bbf_live_…The key is shown once, at creation, and stored only as a hash — we cannot recover it for you. Keys carry scopes: leads:read andleads:write.
GET /api/v1/me
Confirms a key works and reports what it can reach.
curl https://yourbroadbandfinder.com/api/v1/me \
-H "Authorization: Bearer bbf_live_…"GET /api/v1/leads
Lists your leads, newest first.
| Parameter | Description |
|---|---|
since | ISO 8601 timestamp — only leads created after it |
status | new, sent, viewed, contacted, qualified, won, lost, invalid |
limit | 1–100, default 50 |
cursor | next_cursor from the previous page |
curl "https://yourbroadbandfinder.com/api/v1/leads?since=2026-11-01T00:00:00Z&limit=100" \
-H "Authorization: Bearer bbf_live_…"
{
"data": [ { /* lead payload, plus "status" */ } ],
"has_more": true,
"next_cursor": "eyJjIjoiMjAyNi0xMS0xN1QxMDoxMjowMFoifQ=="
}Pagination is keyset, not offset. Follow next_cursor untilhas_more is false. If you poll, prefer since set to the created_at of the newest lead you have stored — with offset pagination, new leads arriving mid-scan would silently push rows past your window.
GET /api/v1/leads/{id}
One lead in full. Returns 404 if it does not belong to your provider.
PATCH /api/v1/leads/{id}
Push the outcome back. This is what makes conversion reporting work, and it is worth more to both of us than the raw lead count. Requires leads:write.
curl -X PATCH https://yourbroadbandfinder.com/api/v1/leads/7c3f1b2a-… \
-H "Authorization: Bearer bbf_live_…" \
-H "Content-Type: application/json" \
-d '{"status":"contacted","note":"Called, install booked Tuesday"}'Errors
{ "error": { "code": "invalid_status", "message": "…" } }| Status | Meaning |
|---|---|
| 400 | Malformed parameter |
| 401 | Missing, malformed, revoked or expired key |
| 403 | Key lacks the required scope |
| 404 | No such lead for this provider |
| 422 | Validation failed |
| 503 | API not enabled on this deployment |
Google Sheets
To use the Google Sheets destination, create an Apps Script bound to your sheet, paste this, deploy it as a web app with access set to "Anyone", and put the deployment URL in the destination's config.
function doPost(e) {
const body = JSON.parse(e.postData.contents);
const name = body.sheet || 'Leads';
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheetByName(name) || ss.insertSheet(name);
sheet.appendRow(body.row);
return ContentService
.createTextOutput(JSON.stringify({ ok: true }))
.setMimeType(ContentService.MimeType.JSON);
}Anyone who finds that URL can append rows, so treat it as a secret and redeploy to rotate it.
Testing
Every destination has a Send test lead button in the portal. It delivers a synthetic lead with event: "lead.test" and an id prefixed test_, so you can wire up and verify an integration before a real customer depends on it. Skip anything with that event if you do not want test rows in your CRM.