Integrating Online Forms with Headless Frontends

When you build your own website frontend, you don't need to integrate a third-party form service just to create a "Contact Us" or "Consultation Request" form. You can create forms directly in the dashboard under "Marketing › Online Forms" and then fetch fields and submit responses from your custom frontend via the Content Delivery API.

Once a form is submitted, Kanorio automatically handles bot protection, spam filtering, creating or merging contacts, sending confirmation emails to submitters, and notifying your team, while triggering the customers.form.submitted webhook.

Full Endpoint and Error Code Specifications (SSOT): For parameter details, field structures, and error codes for the three form endpoints, please refer to the Content Delivery API Reference (Forms Group).

Preparation

1. Create a form and get the Form ID: Go to "Marketing › Online Forms" in your dashboard to create a form. You can find the formId in the URL or under "Data & Records › Data Tables".
2. Register CORS allowed origins: If your frontend calls the API directly from the browser (rather than proxying through your own backend), please go to "Website Settings › Developer" and add your production domain (e.g., https://www.example.com) to "Allowed Origins" (localhost is allowed by default for local development, no setup required).

Three Steps to Integrate

Step 1: Fetch form definition (GET /api/v1/forms/{id})

Fetch the form title, fields, privacy and marketing consent settings, and current availability status when the page loads or builds:

• If availability.accepting is false (e.g., the form is archived or past its deadline), your frontend can display a closed message instead of rendering input fields.
• You can also hardcode form fields in your frontend; just ensure the field.id matches the configuration in the dashboard.

Step 2: Get anti-spam challenge (GET /api/v1/forms/{id}/challenge)

To block automated spam bots without requiring visitors to solve tedious CAPTCHAs, Kanorio uses a lightweight Proof-of-Work challenge:

• Before the visitor focuses on the form or clicks submit, call GET /api/v1/forms/{id}/challenge from the browser (this endpoint is no-store and returns a fresh challenge every time).
• Pass the challenge to your frontend validator to compute the solution string (or use the helper function included in @kanorio/sdk) and include it with your submission.

Step 3: Submit form response (POST /api/v1/forms/{id}/submit)

POST the visitor's answers (an object keyed by field id), the anti-spam solution, and the marketing consent status to /api/v1/forms/{id}/submit:

async function submitContactForm(siteUrl: string, formId: string, answers: Record<string, unknown>) {
  // 1. Get anti-spam challenge and compute solution
  const challengeRes = await fetch(`${siteUrl}/api/v1/forms/${formId}/challenge`, {
    cache: "no-store",
  });
  const challenge = await challengeRes.json();
  const token = await solveFormChallenge(challenge);

  // 2. Submit form answers
  const res = await fetch(`${siteUrl}/api/v1/forms/${formId}/submit`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      answers,
      challengeToken: token,
      marketingConsent: true,
      pagePath: window.location.pathname,
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error?.message ?? "Submission failed");
  }
  return res.json();
}

Automated Backend Workflows

Once /submit returns 200 OK, Kanorio automatically executes the following in the background:

1. Contact Attribution: If the form contains email or phone fields, it automatically matches or creates a and maps custom fields to contact attributes or stores them in the form response.
2. Confirmation and Notifications: Based on your settings in , it automatically sends emails to the submitter and your team.
3. Webhook Push: If you have subscribed to the customers.form.submitted event, the system will immediately push the answers to your external system or automation workflow.

Related Documentation