Skip to main content

AI Lead Form Builder & Submissions REST API Specification

Version: 1.0.0 (2026-08-25)
Target Audience: AI Agents (CrewAI, LangChain, Vercel AI SDK), System Integrators, Frontend Engineers

Overview​

The BizOSaaS Form Builder API provides programmatic endpoints to create, modify, retrieve, publish, and evaluate lead capture forms and form submissions. Every endpoint enforces Row-Level Security (RLS) scoped strictly to app.current_tenant.

Authentication & Headers​

AI Agents and system tools accessing this API via the AI proxy (/api/ai/...) must include the following headers:

  • X-Tenant-ID: Active Tenant UUID (e.g., 714bfb72-2a12-457b-bc48-a45e8f38cdc2)
  • Authorization: Bearer session token or system API key

Endpoint Specifications​

1. GET /api/forms​

Returns all forms owned by the active tenant.

Response 200 OK:

[
  {
    "id": "c1f7a048-5c77-4b71-bdfd-9b5d2a98e29a",
    "tenantId": "714bfb72-2a12-457b-bc48-a45e8f38cdc2",
    "name": "Summer Lead Campaign",
    "type": "embedded",
    "schema": [
      { "id": "field_name", "type": "text", "label": "Full Name", "required": true },
      { "id": "field_email", "type": "email", "label": "Email", "required": true },
      { "id": "gdpr_consent", "type": "consent", "label": "I agree to communications", "required": true }
    ],
    "settings": {
      "submitButtonText": "Get Free Quote",
      "primaryColor": "#6366f1",
      "redirectUrl": "https://example.com/thank-you",
      "gdprEnabled": true
    },
    "status": "active",
    "embedToken": "frm_48a91c0e39a21b",
    "createdAt": "2026-08-25T10:30:00Z"
  }
]

2. POST /api/forms​

Creates a new lead capture form. Used by AI Agents (ContentAgent, CRO Agent) when deploying campaign landers.

Request Payload:

{
  "name": "Q3 Enterprise Consultation",
  "type": "landing_page",
  "schema": [
    { "id": "full_name", "type": "text", "label": "Full Name", "placeholder": "Jane Doe", "required": true },
    { "id": "email", "type": "email", "label": "Work Email", "placeholder": "[email protected]", "required": true },
    { "id": "company_size", "type": "select", "label": "Company Size", "options": ["1-10", "11-50", "50+"], "required": false },
    { "id": "gdpr_consent", "type": "consent", "label": "I agree to privacy policy", "required": true }
  ],
  "settings": {
    "submitButtonText": "Schedule Audit",
    "primaryColor": "#059669",
    "gdprEnabled": true
  }
}

Response 201 Created: Returns created TenantForm object including embedToken.

3. GET /api/forms/:id​

Retrieves a single form definition.

4. PATCH /api/forms/:id​

Updates schema, status, or settings of an existing form.

5. DELETE /api/forms/:id​

Soft-deletes (archives) a form.

6. GET /api/forms/:id/submissions​

Fetches all submissions for a given form.

7. POST /api/forms/:id/submit (Public)​

Public endpoint called by embed widgets and landing pages. Automatically triggers non-blocking deduplicated sync to the tenant's CRM contacts table.

AI Agent Tool Registry Integration​

AI Agents are provisioned with the following tool definitions:

  • create_lead_form: Builds and publishes a form for a specific marketing campaign.
  • get_form_submissions: Reads lead data captured by a form to trigger follow-up email/SMS tasks.
  • update_form_schema: Optimizes form conversion rate by reordering or simplifying fields.