Professional integration docs for agent-run form ops.

<form action="https://hooks.formbox.ai/f/{hookId}/{slug}" method="POST" data-formbox-form>
  <input type="hidden" name="_formbox_secret" value="fbsec_...">
  <input type="text" name="_formbox_hp" tabindex="-1" autocomplete="off" style="position:absolute;left:-9999px" aria-hidden="true">
  <input type="hidden" name="_formbox_started_at" value="">
  <input type="hidden" name="_formbox_field_order" value='["property_type","project_type","project_details","address","city","state","zip","company_name","name","phone","email"]'>
  <fieldset>
    <legend>Property Type</legend>
    <label><input type="radio" name="property_type" value="Residential" checked> Residential</label>
    <label><input type="radio" name="property_type" value="Commercial"> Commercial</label>
  </fieldset>
  <label>
    Project Type
    <input name="project_type" autocomplete="off" required>
  </label>
  <label>
    Project Details
    <textarea name="project_details"></textarea>
  </label>
  <label>
    Street Address
    <input name="address" autocomplete="address-line1" required>
  </label>
  <label>
    City
    <input name="city" autocomplete="address-level2" required>
  </label>
  <label>
    State
    <input name="state" autocomplete="address-level1" maxlength="2" pattern="[A-Za-z]{2}" required>
  </label>
  <label>
    ZIP Code
    <input name="zip" autocomplete="postal-code" inputmode="numeric" pattern="[0-9]{5}" maxlength="5" required>
  </label>
  <label data-company-field hidden>
    Company Name
    <input name="company_name" autocomplete="organization" disabled>
  </label>
  <label>
    Name
    <input name="name" autocomplete="name" required>
  </label>
  <label>
    Phone
    <input name="phone" type="tel" inputmode="tel" autocomplete="tel" pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" required>
  </label>
  <label>
    Email
    <input name="email" type="email" autocomplete="email" required>
  </label>
  <button type="submit">Send</button>
</form>
<script>
(() => {
  const form = document.currentScript && document.currentScript.previousElementSibling;
  if (!(form instanceof HTMLFormElement)) return;

  const companyField = form.querySelector('[data-company-field]');
  const companyInput = form.querySelector('[name="company_name"]');
  const propertyTypeInputs = form.querySelectorAll('[name="property_type"]');
  const startedAtInput = form.querySelector('[name="_formbox_started_at"]');
  if (startedAtInput instanceof HTMLInputElement) startedAtInput.value = String(Date.now());

  const titleCaseWhenLowercase = (value) => {
    const trimmed = value.replace(/\s+/g, ' ').trimStart();
    if (!/[a-z]/.test(trimmed) || trimmed !== trimmed.toLowerCase()) return trimmed;
    return trimmed.replace(/\b[a-z]/g, (letter) => letter.toUpperCase());
  };

  const collapseRepeatedAddress = (value) => {
    const normalized = String(value || '').trim().replace(/\s*,\s*/g, ', ').replace(/\s+/g, ' ');
    const parts = normalized.split(',').map((part) => part.trim()).filter(Boolean);
    if (parts.length === 2 && parts[0].toLowerCase() === parts[1].toLowerCase()) return parts[0];
    return normalized;
  };

  const formatPhone = (value) => {
    const digits = value.replace(/\D/g, '').slice(0, 10);
    if (digits.length <= 3) return digits;
    if (digits.length <= 6) return digits.slice(0, 3) + '-' + digits.slice(3);
    return digits.slice(0, 3) + '-' + digits.slice(3, 6) + '-' + digits.slice(6);
  };

  const syncCompanyField = () => {
    const checked = form.querySelector('[name="property_type"]:checked');
    const isCommercial = checked && checked.value === 'Commercial';
    if (companyField instanceof HTMLElement) companyField.hidden = !isCommercial;
    if (companyInput instanceof HTMLInputElement) {
      companyInput.disabled = !isCommercial;
      companyInput.required = Boolean(isCommercial);
      if (!isCommercial) companyInput.value = '';
    }
  };

  const normalizeField = (input) => {
    if (['name', 'company_name', 'address', 'city'].includes(input.name)) input.value = titleCaseWhenLowercase(input.name === 'address' ? collapseRepeatedAddress(input.value) : input.value);
    if (input.name === 'email') input.value = input.value.trim().toLowerCase();
    if (input.name === 'phone') input.value = formatPhone(input.value);
    if (input.name === 'state') input.value = input.value.replace(/[^a-z]/gi, '').slice(0, 2).toUpperCase();
    if (input.name === 'zip') input.value = input.value.replace(/\D/g, '').slice(0, 5);
    if (input instanceof HTMLTextAreaElement) input.value = input.value.replace(/\s+/g, ' ').trim();
  };

  propertyTypeInputs.forEach((input) => input.addEventListener('change', syncCompanyField));
  form.addEventListener('input', (event) => {
    const input = event.target;
    if (!(input instanceof HTMLInputElement || input instanceof HTMLTextAreaElement)) return;
    normalizeField(input);
  });
  form.addEventListener('submit', () => {
    form.querySelectorAll('input:not([type="hidden"]):not([type="radio"]), textarea').forEach((field) => {
      if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) normalizeField(field);
    });
  });
  syncCompanyField();
})();
</script>

await fetch("https://hooks.formbox.ai/f/{hookId}/{slug}", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-FormBox-Secret": "fbsec_...",
  },
  body: JSON.stringify({
    payload: {
      property_type: "Residential",
      project_type: "Driveway gate",
      project_details: "Hello from FormBox",
      name: "Test Lead",
      phone: "801-555-0100",
      email: "test@example.com",
    },
    metadata: {
      fieldOrder: ["property_type", "project_type", "project_details", "name", "phone", "email"],
      pageUrl: "https://demo-site.com/quote?utm_source=google&utm_medium=cpc",
      landingPageUrl: "https://demo-site.com/?utm_source=google&utm_medium=cpc&gclid=test123",
      referrer: "https://www.google.com/",
      userAgent: navigator.userAgent,
      utm: {
        source: "google",
        medium: "cpc",
        campaign: "spring-gates",
      },
      clickIds: {
        gclid: "test123",
      },
    },
  }),
});

// Browser -> /api/quote on the same website -> FormBox
export async function POST(request) {
  const body = await request.json();

  // Verify Turnstile/captcha here when the website uses one.
  // Normalize fields before forwarding: phone, email, state, ZIP, etc.

  const response = await fetch(process.env.FORMBOX_INTAKE_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-FormBox-Secret": process.env.FORMBOX_HOOK_SECRET,
    },
    body: JSON.stringify({
      payload: {
        property_type: body.property_type,
        project_details: body.project_details,
        name: body.name,
        phone: body.phone,
        email: body.email,
      },
      metadata: {
        fieldOrder: ["property_type", "project_details", "name", "phone", "email"],
        pageUrl: body._formbox_page_url,
        landingPageUrl: body._formbox_landing_page_url,
        referrer: body._formbox_referrer,
        userAgent: request.headers.get("user-agent") || body._formbox_user_agent,
        utm: {
          source: body._formbox_utm_source,
          medium: body._formbox_utm_medium,
          campaign: body._formbox_utm_campaign,
          term: body._formbox_utm_term,
          content: body._formbox_utm_content,
        },
        clickIds: {
          gclid: body._formbox_gclid,
          gbraid: body._formbox_gbraid,
          wbraid: body._formbox_wbraid,
          fbclid: body._formbox_fbclid,
          msclkid: body._formbox_msclkid,
        },
      },
    }),
  });

  if (!response.ok) return Response.json({ ok: false }, { status: 502 });
  return Response.json({ ok: true });
}

<form action="https://hooks.formbox.ai/f/{hookId}/{slug}" method="POST" enctype="multipart/form-data">
  <input type="hidden" name="_formbox_secret" value="fbsec_...">
  <input type="hidden" name="_formbox_field_order" value='["name","phone","project_details","photos"]'>
  <input name="name" required>
  <input name="phone" type="tel" required>
  <textarea name="project_details"></textarea>
  <input name="photos" type="file" accept="image/*,.pdf,.doc,.docx,.txt" multiple>
  <button type="submit">Send</button>
</form>

// Run on every page, before the visitor reaches the form.
const ATTRIBUTION_KEY = "formbox_attribution_v1";
const TTL_MS = 90 * 24 * 60 * 60 * 1000;
const params = new URLSearchParams(window.location.search);
const stored = JSON.parse(localStorage.getItem(ATTRIBUTION_KEY) || "null");
const fresh = !stored || Date.now() - stored.createdAt > TTL_MS;
const hasSource = ["utm_source", "utm_medium", "utm_campaign", "gclid", "gbraid", "wbraid", "fbclid", "msclkid"].some((key) => params.get(key));

if (fresh || (!stored?.hasClickId && hasSource)) {
  const attribution = {
    createdAt: Date.now(),
    landingPageUrl: window.location.href,
    referrer: document.referrer,
    hasClickId: Boolean(params.get("gclid") || params.get("gbraid") || params.get("wbraid") || params.get("fbclid") || params.get("msclkid")),
    utm: {
      source: params.get("utm_source"),
      medium: params.get("utm_medium"),
      campaign: params.get("utm_campaign"),
      term: params.get("utm_term"),
      content: params.get("utm_content"),
    },
    clickIds: {
      gclid: params.get("gclid"),
      gbraid: params.get("gbraid"),
      wbraid: params.get("wbraid"),
      fbclid: params.get("fbclid"),
      msclkid: params.get("msclkid"),
    },
  };
  localStorage.setItem(ATTRIBUTION_KEY, JSON.stringify(attribution));
  sessionStorage.setItem(ATTRIBUTION_KEY, JSON.stringify(attribution));
}

document.addEventListener("submit", (event) => {
  const form = event.target;
  if (!(form instanceof HTMLFormElement)) return;
  const attribution = JSON.parse(sessionStorage.getItem(ATTRIBUTION_KEY) || localStorage.getItem(ATTRIBUTION_KEY) || "{}");
  const setHidden = (name, value) => {
    if (!value) return;
    let input = form.querySelector('input[name="' + name + '"]');
    if (!input) {
      input = document.createElement("input");
      input.type = "hidden";
      input.name = name;
      form.appendChild(input);
    }
    input.value = String(value);
  };

  setHidden("_formbox_page_url", window.location.href);
  setHidden("_formbox_landing_page_url", attribution.landingPageUrl);
  setHidden("_formbox_referrer", attribution.referrer || document.referrer);
  setHidden("_formbox_user_agent", navigator.userAgent);
  setHidden("_formbox_utm_source", attribution.utm?.source);
  setHidden("_formbox_utm_medium", attribution.utm?.medium);
  setHidden("_formbox_utm_campaign", attribution.utm?.campaign);
  setHidden("_formbox_utm_term", attribution.utm?.term);
  setHidden("_formbox_utm_content", attribution.utm?.content);
  setHidden("_formbox_gclid", attribution.clickIds?.gclid);
  setHidden("_formbox_gbraid", attribution.clickIds?.gbraid);
  setHidden("_formbox_wbraid", attribution.clickIds?.wbraid);
  setHidden("_formbox_fbclid", attribution.clickIds?.fbclid);
  setHidden("_formbox_msclkid", attribution.clickIds?.msclkid);
}, true);

Authorization: Bearer fb_...

curl -X POST https://app.formbox.ai/api/v1/provision-site-intake   -H "Authorization: Bearer fb_..."   -H "Content-Type: application/json"   -d '{
    "domain": "demo-site.com",
    "forms": [
      {
        "name": "Quote Request",
        "notificationEmail": "leads@demo-site.com",
        "notificationCcEmails": ["owner@demo-site.com"],
        "allowedOrigins": ["https://demo-site.com", "https://www.demo-site.com"]
      }
    ]
  }'

curl -X POST https://hooks.formbox.ai/f/{hookId}/{slug}   -H "Content-Type: application/json"   -H "X-FormBox-Secret: fbsec_..."   -d '{"payload":{"name":"Test Lead","email":"test@example.com","message":"Hello from FormBox"},"metadata":{"fieldOrder":["name","email","message"]}}'