Forms API

Internal documentation for developers. This page covers the Forms API: form creation, chat widget embedding, submission processing, and the form builder schema. Not intended for end users.

Route Map

Method	Endpoint	Handler File	Description
`GET`	`/api/forms`	`forms/route.ts`	List all forms
`POST`	`/api/forms`	`forms/route.ts`	Create a form
`GET`	`/api/forms/[formId]`	`forms/[formId]/route.ts`	Get form by ID
`PATCH`	`/api/forms/[formId]`	`forms/[formId]/route.ts`	Update form
`DELETE`	`/api/forms/[formId]`	`forms/[formId]/route.ts`	Delete form
`POST`	`/api/forms/[formId]/chat`	`forms/[formId]/chat/route.ts`	Submit form response via chat
`GET`	`/api/forms/[formId]/submissions`	`forms/[formId]/submissions/route.ts`	List form submissions

Auth Pattern

Forms have dual access patterns: Authenticated (dashboard):

withPermissionRoute(req, { permission: 'forms.manage' }, handler)

Public (embedded widget):

POST /api/forms/[formId]/chat can be called without authentication
Protected by formId secrecy (HMAC-signed if needed)

Form Schema

Forms are defined as a JSON schema stored in the config field:

interface FormConfig {
  fields: FormField[];
  submitButtonText: string;
  successMessage: string;
  agentId?: string;      // AI to process submission
  webhookUrl?: string;   // External webhook on submit
}

interface FormField {
  id: string;
  type: 'text' | 'email' | 'phone' | 'select' | 'multiselect' | 'textarea' | 'number';
  label: string;
  placeholder?: string;
  required: boolean;
  options?: string[];    // for select/multiselect
  validation?: {
    pattern?: string;    // regex
    min?: number;
    max?: number;
  };
}

Chat Submission Endpoint

The POST /api/forms/[formId]/chat endpoint processes a form submission through the AI:

// Input: form field responses
// Processing:
// 1. Validate all required fields
// 2. Create Contact from submission data (if email/phone provided)
// 3. Create Conversation linked to the form
// 4. Pass responses to assigned AI Employee
// 5. AI generates a personalized response
// 6. Return AI response + conversationId

This powers the form widget’s conversational experience.

Streaming Contract

forms/[formId]/chat/route.ts returns a text/event-stream response immediately, then delegates execution to the assigned agent through /api/agents/[id]/query. The route buffers endpoint_response chunks and validates the final payload with ChatResponse.safeParse before reading answer, messageId, or metadata. The route emits metadata SSE events only for typed form-state updates:

{
  currentField: string;
  isValid: boolean;
}

When a final messageId is present, the persisted message is updated with the marker-stripped answer and the typed form metadata. Parsing failures in tool or endpoint buffers are ignored deliberately; malformed buffers do not create partial database writes.

Submissions

// GET /api/forms/[formId]/submissions
// Returns all submissions for a form
// Each submission: { id, contactId, data: JSON, createdAt }

Submissions are stored as JSON blobs — the exact structure depends on the form’s field schema.

Prisma Indexes Used

Table	Index	Used by
`Form`	`organizationId`	List forms
`FormSubmission`	`formId`	List submissions per form
`FormSubmission`	`contactId`	Contact’s submission history

Known Issues / Gotchas

Public chat endpoint: The formId is the only secret protecting public form submissions. For sensitive forms, consider adding HMAC signing or reCAPTCHA.
Submission JSON schema evolution: If form fields change after submissions exist, old submissions may have fields that no longer match the current schema. UI must handle missing fields gracefully.
AI processing timeout: The chat submission endpoint calls the AI, which can take up to 30 seconds for complex forms. Configure appropriate Next.js function timeout.
Webhook delivery: External webhook on submit is fire-and-forget. Implement retry logic in @zappway/lib/webhooks if reliability is required.

API Internals

Infrastructure

Route Map

Auth Pattern

Form Schema

Chat Submission Endpoint

Streaming Contract

Submissions

Prisma Indexes Used

Known Issues / Gotchas

​Route Map

​Auth Pattern

​Form Schema

​Chat Submission Endpoint

​Streaming Contract

​Submissions

​Prisma Indexes Used

​Known Issues / Gotchas

Route Map

Auth Pattern

Form Schema

Chat Submission Endpoint

Streaming Contract

Submissions

Prisma Indexes Used

Known Issues / Gotchas