Skip to content
For providers

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.

  1. Push — we POST each lead to a destination you configure.
  2. Pull — your system polls GET /api/v1/leads.
  3. 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.

TypeWhat it does
webhookPOST each lead as JSON to your own endpoint, signed with HMAC-SHA256 so you can verify it came from us.
zapierPaste a Zapier "Catch Hook" or Make "Custom webhook" URL and route leads into any of their thousands of apps.
slackPost each lead into a Slack channel via an incoming webhook.
hubspotCreate a HubSpot contact for each lead using a private app token.
pipedriveCreate a Pipedrive person and an attached lead.
salesforceSubmit each lead through your Salesforce Web-to-Lead endpoint. No OAuth setup required.
google_sheetsAppend each lead as a row. Deploy the Apps Script snippet from our docs and paste its web app URL here.
emailSend 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

HeaderValue
X-BBF-Eventlead.created or lead.test
X-BBF-DeliveryUnique id for this delivery attempt chain
X-BBF-Signaturet=<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.

ParameterDescription
sinceISO 8601 timestamp — only leads created after it
statusnew, sent, viewed, contacted, qualified, won, lost, invalid
limit1–100, default 50
cursornext_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": "…" } }
StatusMeaning
400Malformed parameter
401Missing, malformed, revoked or expired key
403Key lacks the required scope
404No such lead for this provider
422Validation failed
503API 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.