Managed Forms

Add data-buckhy-form="contact" to a <form>. The Engage SDK intercepts the submit, posts the fields to Buckhy, and writes a success or error message into your page. Each submission is stored as a ticket (ENG-F-…) and appears in the website's Inbox > Leads. Notification email and configured webhook delivery are separate outcomes.

Your markup and styling stay exactly as they are. Managed Forms is delivered by the Engage SDK with a publishable key.

1. The SDK enhances form[data-buckhy-form] at startup and watches added DOM nodes and form attributes for SPA navigation.
2. On submit it checks validity and collects successful string controls, then posts POST /v1/engage/forms/:form with an Idempotency-Key. Buckhy sanitizes fields and drops honeypots server-side.
3. Buckhy enforces the bound website/environment form policy, stores a ticket with source form, and queues notifications. The response includes success, id and the configured successMessage when a form policy applies. A 201 does not prove email or webhook delivery; inspect delivery status.
4. The SDK writes the success text (or the error message) into the data-buckhy-status element and dispatches the matching DOM event.

1. Open Businesses, add or select your website, and verify domain ownership. Choose Test for local development or Live for your production website.
2. Open Apps > Managed Forms > Configure. Set the app's fields and exact allowed origins. HTTP localhost origins belong only in Test.
3. In Integrate, create or reuse the environment's Engage credential. Keep one SDK loader when another Engage app is already installed:

<script src="https://api.buckhy.com/v1/engage/sdk.js" defer
  data-site-key="bk_live_…"></script>

Complete the Forms interaction below, then open Test, run the checks and continue to Activate. Creating a credential or copying this snippet does not complete activation. 4. Mark up a form:

<form data-buckhy-form="contact"
      data-buckhy-success="Thanks — we reply within one business day.">
  <input name="name" required />
  <input name="email" type="email" required />
  <textarea name="message" required></textarea>

  <!-- Honeypot: hidden from people, dropped by Buckhy -->
  <input name="website" tabindex="-1" autocomplete="off"
         style="position:absolute;left:-9999px" />

  <button type="submit">Send</button>
  <p data-buckhy-status role="status"></p>
</form>

5. Submit it and inspect Businesses > your website > Inbox > Leads. Check notification delivery separately, then complete Test > Run checks > Activate.

Framework install and a copy-paste AI-agent prompt that converts your forms: Install the Engage SDK.

Convert an existing form

Add the attribute, keep every field, add an off-screen honeypot named website, add an empty status element, and remove any existing submit handler that would post a second time. Nothing else changes.

React to the result

form.addEventListener("buckhy:submitted", (e) => {
  console.log("stored as", e.detail.id); // "ENG-F-…"
  form.reset();
});
form.addEventListener("buckhy:error", (e) => {
  console.error(e.detail.message);      // e.g. "fields are required"
});

Post from your own code

Without the SDK — from a mobile app or a backend — call the endpoint directly:

await fetch("https://api.buckhy.com/v1/engage/forms/contact", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": SITE_KEY,
    "Idempotency-Key": crypto.randomUUID(), // once per submission, reused on retry
  },
  body: JSON.stringify({ page: "/contact", fields: { name, email, message } }),
});

Requests without an Origin header (servers, native apps) are accepted; browser requests must come from an allowed origin.

How fields become a ticket