Forms

The Konigle SDK provides functionality to manage forms and form submissions from the Konigle Forms service. Forms allow you to collect data from users, with built-in spam detection, CAPTCHA support, and email notifications.

Overview

Forms are managed through a separate service at https://forms.konigle.com and support:

• Form creation with auto-generated slugs
• CAPTCHA integration for spam prevention
• Submission tracking with metadata (IP, country, user agent)
• Built-in spam detection with confidence scoring
• Email notification tracking

Prerequisites

Before using the Forms API, ensure you have the Konigle forms account configured with the project. The SDK automatically fetches the necessary credentials from this connection.

Creating Forms

Basic Form Creation

import konigle
from konigle.models.core import FormCreate

client = konigle.Client(api_key="your-api-key")

# Create a simple contact form
form_data = FormCreate(
    name="Contact Form"
)

form = client.forms.create(form_data)
print(f"Created form: {form.id}")
print(f"Form slug: {form.slug}")  # Auto-generated from name
print(f"Form name: {form.name}")

The slug is automatically generated from the form name (e.g., "Contact Form" becomes "contact-form").

Listing Forms

Basic Listing

import konigle

client = konigle.Client(api_key="your-api-key")

# List all forms
forms = client.forms.list()

print(f"Found {forms.count} forms")
for form in forms.payload:
    print(f"  • {form.name} (slug: {form.slug})")

Paginated Listing

# List forms with pagination
page1 = client.forms.list(page=1, page_size=10)

print(f"Page {page1.current_page} of {page1.num_pages}")
print(f"Total forms: {page1.count}")

for form in page1.payload:
    print(form)

# Navigate to next page
if page1.has_next():
    page2 = client.forms.list(page=2, page_size=10)

Getting Form Submissions

# Get submissions for a specific form
submissions = client.forms.list_submissions(
    slug="contact-form",
    page=1,
    page_size=20
)

print(f"Found {submissions.count} submissions for 'contact-form'")

for submission in submissions.payload:
    print(f"\nSubmission ID: {submission.id}")
    print(f"  Submitted at: {submission.submitted_at}")
    print(f"  IP Address: {submission.ip_address}")
    print(f"  Country: {submission.country or 'Unknown'}")
    print(f"  Is Spam: {submission.is_spam}")

    # Access form data
    print(f"  Form Data: {submission.form_data}")

    # Check spam details
    if submission.is_spam:
        print(f"  Spam Confidence: {submission.spam_confidence:.2f}")
        print(f"  Spam Reason: {submission.spam_reason}")

CLI Usage

Use the CLI for quick form management:

# List all forms
konigle forms list

# List with pagination
konigle forms list --page 1 --page-size 5

# Create a new form
konigle forms create --name "Newsletter Signup"

# Get details of a specific form
konigle forms get contact-form

# List submissions for a form
konigle forms submissions contact-form

# List submissions with pagination
konigle forms submissions contact-form --page 1 --page-size 20

Async Operations

import asyncio
import konigle

async def manage_forms():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # List forms asynchronously
        forms = await client.forms.list()

        print(f"Found {forms.count} forms")

        # Get submissions for each form
        for form in forms.payload:
            print(f"\nProcessing submissions for: {form.name}")

            submissions = await client.forms.list_submissions(
                slug=form.slug,
                page_size=10
            )

            # Count spam vs legitimate
            spam_count = sum(1 for s in submissions.payload if s.is_spam)
            legit_count = len(submissions.payload) - spam_count

            print(f"  Total: {submissions.count} submissions")
            print(f"  Legitimate: {legit_count}")
            print(f"  Spam: {spam_count}")

# Run async operation
asyncio.run(manage_forms())