Forms & Lead Capture

Capture leads from your website into Breadbox — three ways, depending on what your team can build.

Webhook URL — paste into your form tool

In Breadbox, go to Settings → Forms & Lead Capture and create a new form. Copy the inbound URL it gives you. Format:

https://app.breadboxmsp.com/api/inbound/<orgId>/<slug>?token=<token>

Paste that URL into your form tool. Breadbox auto-detects common field names (email, first name, etc.) so most submissions work out of the box. If your form tool uses non-standard field names, configure explicit field mappings on the Mapping tab.

Tool-specific setup

<form id="contactForm">
  <input name="firstName" required />
  <input name="lastName" required />
  <input name="email" type="email" required />
  <input name="company" />
  <textarea name="message"></textarea>

  <!-- Honeypot — leave hidden + empty. Bots fill it; we reject. -->
  <input name="website_url" type="text" style="display:none" tabindex="-1" autocomplete="off" />

  <button type="submit">Submit</button>
</form>

<script>
document.getElementById('contactForm').addEventListener('submit', async (e) => {
  e.preventDefault();
  const formData = new FormData(e.target);
  const body = Object.fromEntries(formData.entries());

  const res = await fetch('https://app.breadboxmsp.com/api/inbound/<orgId>/<slug>?token=<token>', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });

  if (res.ok) {
    e.target.innerHTML = '<p>Thanks — we&apos;ll be in touch.</p>';
  } else {
    alert('Something went wrong. Please try again.');
  }
});
</script>

Field mapping

When Breadbox receives a submission, it needs to know which incoming field is the email, which is the first name, etc. There are two paths:

1. Auto-detect (default) — we recognize common field names like email, first_name, contact_first_name, q1_email, etc. across dozens of synonyms. Works for ~90% of form tools out of the box.
2. Explicit mapping — if your form tool sends odd field names (e.g. field_2493), open the form's Mapping tab and configure each one. Use the Test tab to paste a sample payload and see what would happen.

Mappable target fields:

Spam protection

Public form URLs attract bot traffic. Breadbox layers four protections:

1. Token validation — every URL has a per-form 32-char token. Without it, submissions return 404. Rotate the token from the Setup tab if it leaks.
2. IP rate limit — 10 submissions per minute per source IP. Beyond that, 429.
3. Form-level rate limit — 100 submissions per hour per form. Catches abuse even when traffic is distributed across IPs.
4. Honeypot field (recommended) — add a hidden field named e.g. website_url in your form HTML. Real users won't fill it; bots will. We silently reject those submissions and bump the spam-blocked counter.
5. reCAPTCHA v3 (optional) — for high-traffic forms, enable Google reCAPTCHA v3. Sign up at google.com/recaptcha/admin, create a v3 key, paste both site key and secret into the form's Spam tab. Embed the site key in your form to generate tokens; we verify server-side with score threshold 0.5.

REST API — for developers

If you have a developer-built backend, use the public API. Authenticated, scoped, audit- logged. Different from the inbound URL — uses a Bearer token, supports idempotency keys, and returns full Lead data.

curl -X POST https://app.breadboxmsp.com/api/v1/leads \
  -H "Authorization: Bearer msp_live_xxxxx" \
  -H "Idempotency-Key: form-submission-$REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Healthcare",
    "contactFirstName": "Sarah",
    "contactLastName": "Chen",
    "contactEmail": "sarah@acme.example",
    "contactPhone": "(617) 555-0142",
    "industry": "Healthcare",
    "employeeCount": 65,
    "source": "INBOUND_WEB",
    "notes": "Submitted contact form on /pricing"
  }'

Full reference: /docs/api. Idempotency keys mean you can safely retry on network failure — same key returns the cached response.

Troubleshooting