KirokuForms Quick Start Guide

Get your custom HTML form integrated with KirokuForms and collecting submissions in minutes. This guide focuses on client-side JavaScript submission to our secure API endpoint.

Before You Begin

Ensure you have the following ready:

A KirokuForms Account. (It's free to get started!)
A Form ID : Create a new form in your KirokuForms Dashboard or use an existing one. You'll find the Form ID on the form's settings page (usually in the URL or displayed prominently).
An API Key : Go to your Developer Settings in the dashboard to generate an API Key. Make sure it has the forms:submit scope permission.

Important Security Note

This quick start example uses an API Key directly in client-side JavaScript for simplicity. Never expose sensitive API keys with broad permissions in your frontend code in a production environment.
For production, always prefer submitting data through your own backend server, where your API key can be kept secret. If you must use client-side submission, ensure you use API keys with the absolute minimum necessary scope (like forms:submit only for a specific form if possible) and consider rate limiting and origin restrictions.

Step 1: Your HTML Form Structure

First, set up the HTML for your form. You can include any fields your KirokuForm is configured to accept. We'll use JavaScript to handle the submission, so the <form> tag itself doesn't need action or method attributes. Make sure to give your form, submit button, and status display area unique id attributes.

Example HTML Form (your-page.html)

<form id="kirokuQuickstartForm">
  <div style="margin-bottom: 1rem;">
    <label for="name" style="display: block; margin-bottom: 0.25rem; font-family: Inter, sans-serif; color: #334155;">Name:</label>
    <input type="text" id="name" name="name" required style="width: 100%; padding: 0.5rem; border: 1px solid #d1d5db; border-radius: 0.375rem; font-family: Inter, sans-serif;" />
  </div>

  <div style="margin-bottom: 1rem;">
    <label for="email" style="display: block; margin-bottom: 0.25rem; font-family: Inter, sans-serif; color: #334155;">Email:</label>
    <input type="email" id="email" name="email" required style="width: 100%; padding: 0.5rem; border: 1px solid #d1d5db; border-radius: 0.375rem; font-family: Inter, sans-serif;" />
  </div>

  <div style="margin-bottom: 1rem;">
    <label for="message" style="display: block; margin-bottom: 0.25rem; font-family: Inter, sans-serif; color: #334155;">Message (Optional):</label>
    <textarea id="message" name="message" rows="4" style="width: 100%; padding: 0.5rem; border: 1px solid #d1d5db; border-radius: 0.375rem; font-family: Inter, sans-serif;"></textarea>
  </div>

  <button type="submit" id="kirokuSubmitButton" style="padding: 0.75rem 1.5rem; background-color: #2563EB; color: white; border: none; border-radius: 0.375rem; cursor: pointer; font-family: Inter, sans-serif; font-weight: 500;">
    Submit to KirokuForms
  </button>
</form>

<div id="kirokuFormStatus" style="margin-top: 1rem; padding: 0.75rem; border-radius: 0.375rem; font-family: Inter, sans-serif; display: none;"></div>

The inline styles are just for this example. You should style your form using your project's CSS. KirokuForms won't interfere with your form's appearance when using this API submission method. Read more about styling options.

Step 2: JavaScript for API Submission

Next, add the following JavaScript to your page. This script will listen for your form's submit event, prevent the default browser action, collect the data, and send it as JSON to the KirokuForms API endpoint: https://www.kirokuforms.com/api/forms/YOUR_FORM_ID/submit.

Remember to replace YOUR_FORM_ID and YOUR_KIROKU_API_KEY with your actual values.

Submission Script (inline or your-script.js)

// Add this script to your webpage, ideally just before your closing </body> tag

const form = document.getElementById('kirokuQuickstartForm');
const statusDiv = document.getElementById('kirokuFormStatus');
const submitButton = document.getElementById('kirokuSubmitButton');

// --- Configuration ---
// Replace with your actual Form ID from the KirokuForms Dashboard
const YOUR_FORM_ID = 'REPLACE_WITH_YOUR_FORM_ID';
// Replace with your actual API Key (ensure it has 'forms:submit' scope)
const YOUR_API_KEY = 'REPLACE_WITH_YOUR_KIROKU_API_KEY';
// ---------------------

if (form && statusDiv && submitButton) {
  form.addEventListener('submit', async (event) => {
    event.preventDefault(); // Prevent default browser submission

    if (submitButton.disabled) return; // Prevent multiple submissions

    // Provide user feedback
    submitButton.disabled = true;
    submitButton.textContent = 'Submitting...';
    statusDiv.textContent = '';
    statusDiv.style.display = 'none'; // Hide previous status

    const formData = new FormData(form);
    const data = Object.fromEntries(formData.entries());

    try {
      const response = await fetch(`https://www.kirokuforms.com/api/forms/${YOUR_FORM_ID}/submit`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${YOUR_API_KEY}`,
          'Accept': 'application/json' // Expect a JSON response
        },
        body: JSON.stringify(data)
      });

      // Restore button state
      submitButton.disabled = false;
      submitButton.textContent = 'Submit to KirokuForms';

      const result = await response.json(); // Try to parse JSON regardless of response.ok

      if (response.ok) {
        console.log('KirokuForms Submission Success:', result);
        statusDiv.textContent = result.message || 'Submission successful! Thank you.';
        statusDiv.style.backgroundColor = '#dcfce7'; // Tailwind green-100
        statusDiv.style.color = '#166534';       // Tailwind green-800
        statusDiv.style.border = '1px solid #a7f3d0'; // Tailwind green-200
        statusDiv.style.display = 'block';
        form.reset();
      } else {
        console.error('KirokuForms Submission Error:', result);
        statusDiv.textContent = `Error (${response.status}): ${result.error?.message || result.message || 'An unknown error occurred.'}`;
        if (result.error?.details) {
          statusDiv.innerHTML += '<br><small>' + JSON.stringify(result.error.details) + '</small>';
        }
        statusDiv.style.backgroundColor = '#fee2e2'; // Tailwind red-100
        statusDiv.style.color = '#b91c1c';       // Tailwind red-700
        statusDiv.style.border = '1px solid #fecaca'; // Tailwind red-200
        statusDiv.style.display = 'block';
      }
    } catch (error) {
      console.error('Network or script error during submission:', error);
      statusDiv.textContent = 'A network error occurred. Please check your connection and try again.';
      statusDiv.style.backgroundColor = '#fee2e2'; // Tailwind red-100
      statusDiv.style.color = '#b91c1c';       // Tailwind red-700
      statusDiv.style.border = '1px solid #fecaca'; // Tailwind red-200
      statusDiv.style.display = 'block';
      // Restore button state
      submitButton.disabled = false;
      submitButton.textContent = 'Submit to KirokuForms';
    }
  });
} else {
  console.warn('KirokuForms Quick Start: Form elements (form, status div, or submit button) not found. Ensure IDs match.');
}

Key points in the script:

It uses fetch to make an asynchronous POST request.
Content-Type: application/json is set, so the data is sent as JSON.
Authorization: Bearer YOUR_API_KEY provides authentication.
It includes basic error handling and updates the kirokuFormStatus div.

Step 3: Test Your Form

Now it's time to see it in action:

Save your HTML file with the form structure and the JavaScript snippet.
Open the HTML file in your web browser.
Fill out the form fields.
Open your browser's Developer Console (usually by pressing F12) to watch for any log messages.
Click the "Submit to KirokuForms" button.
You should see a success message on your page and in the console.
Go to your KirokuForms Dashboard. Your new submission should be there!

Troubleshooting

If you encounter issues, double-check:

Your Form ID and API Key are correct in the JavaScript.
The API Key has the forms:submit scope.
Your KirokuForm is set to "Active".
There are no errors in the browser console.
The domain your form is on is listed in your form's "Allowed Origins" if you've configured that setting in KirokuForms. (For local testing like file:// or localhost, you might need to temporarily allow all origins or add these specific ones).

Alternative: Using the Public Form URL (No Custom Code)

If you don't want to write any JavaScript or manage API keys on your website for a simple use case, the easiest way to collect data is to direct your users to the public URL of your KirokuForm.

In your KirokuForms Dashboard, open the form you want to use.
Find its "Public URL" (usually looks like https://www.kirokuforms.com/f/your-form-slug).
Simply link to this URL from your website. KirokuForms hosts the form, handles the submission, and displays success/error messages or redirects as you've configured in the form settings.

This method doesn't require any coding on your part beyond adding a link.

Next Steps

Congratulations on successfully submitting data from your custom form to KirokuForms!

Here’s what you can explore next to enhance your integration:

Server-Side Integration
For optimal security, especially with API keys, learn how to submit form data from your backend server.
Advanced Styling & Frameworks
Discover more about custom CSS, using KirokuForms with React/Vue, and other advanced examples.
Webhooks for Real-Time Data
Get instant notifications sent to your server whenever new submissions arrive.
Full API Reference
Explore all available KirokuForms API endpoints and their capabilities.

Need more help? Visit our Support Center or go back to the Developer Hub.