# Forms

Karmaflow.ai has two features called forms, and they do different jobs:

- **Form endpoints** (CRM) receive submissions from forms on **your own website** and turn them into contacts. You keep your page, your design and your form; Karmaflow.ai gives you an address to post it to.
- **Agent forms** tell an AI agent which fields to collect during a conversation — a chat, a call, a task run — and hand the answers back in a fixed shape.

## Form endpoints

A form endpoint is not a form builder. It is a secure address — `https://omni.karmaflow.ai/api/forms/<your-workspace>/<form>` — plus an API key, a field map and a submissions log. Your website posts to the address; Karmaflow.ai matches or creates the contact, runs your workflows and keeps every submission.

```mermaid
flowchart LR
    V[Visitor fills in<br/>the form on your site] --> J[Your page posts the fields<br/>with the API key]
    J --> E[Form endpoint]
    E --> S{Checks}
    S -->|origin, rate limit,<br/>reCAPTCHA, AI spam score| M[Field map]
    M -->|email matches| U[Contact updated]
    M -->|new email| C[Contact created<br/>as a lead]
    U & C --> T[Timeline entry · workflow trigger<br/>notification email · GA4 lead event]
```

### Why teams use it

- **No vendor form on your page.** Any HTML form, any framework, any site builder that lets you add a few lines of script. The look stays yours.
- **Fields you name, mapped once.** Send a test submission and the endpoint lists the fields it saw. Map each one to a contact field — including a *Full Name → First Name + Last Name* split, a note, or a custom field created on the spot.
- **Protection built in.** Allowed origins, a per-minute rate limit, optional Google reCAPTCHA v3, and an AI spam score that quietly files gibberish and pattern-flood submissions as spam while still telling the bot it succeeded.
- **Ad attribution for free.** With the Karmaflow.ai tracker on the page, the click id, campaign tags and GA4 session that brought the visitor travel with the submission onto the contact and a `generate_lead` event reaches GA4 — see [Google Analytics 4 workflows](/help/integrations/google-analytics-workflows).
- **An email door too.** Each endpoint can have its own address; mail sent there is read by AI and becomes a submission — handy for a partner who emails leads instead of posting them.

### What happens on a submission

| Step | What Karmaflow.ai does |
|---|---|
| Accept | Checks the API key, the page's origin against **Allowed Origins**, the rate limit, and reCAPTCHA if enabled. |
| Score | Scores the submission for spam against the last ten. Spam is stored and labelled, and the sender still sees a success — so a bot learns nothing. |
| Match | Looks up the contact by **email**. A match is updated; a new address becomes a contact in the *lead* lifecycle stage. A submitter on one of your own domains is stored but gets no contact. |
| Record | Writes *Submitted web form "…"* on the contact's Activity Timeline, fires the **Form Endpoint Submission** workflow trigger for that form, emails your **Email Recipients**, and sends the GA4 lead event when the integration is on. |

Everything is kept on the endpoint's **Submissions** page with its status — *Test*, *Received*, *Processed*, *Failed* or *Spam* — and the CRM outcome.

### Set one up

The step-by-step is in **[Connecting a Website Form](/help/forms/connect-a-website-form)**: create the endpoint, copy the key, send a test from your page, map the fields, go live.

## Agent forms

An agent form is a template of fields — **Text** or **Picklist** — that you attach to a chat, voice or task agent. During the interaction the agent works to fill each field and returns the captured values in the same structure every time, so a downstream workflow can rely on them.

1. Go to **Agents → Workflows → Agent Forms** and click **Create New Form**.
2. In the **Agent Form Builder**, name the form and add fields; a Picklist field takes its options here.
3. Save, then select the form on the agent that should collect it.

Agent forms have no public address and nothing to embed — the agent is the form. A completed agent form fires the **Agent Form Submission** workflow trigger.

## Which one do I want?

| You want to… | Use |
|---|---|
| Capture leads from a page on your website | A form endpoint |
| Let a partner email you leads | A form endpoint with **Email Intake** on |
| Have the chat widget or a voice agent ask for specific details | An agent form on that agent |
| Start a workflow when any of these completes | The matching trigger — **Form Endpoint Submission** or **Agent Form Submission** |

Permissions: form endpoints need `crm:forms:read` to view and `crm:forms:manage` to create or edit; agent forms need manage rights on any agent type.

## Learn more

- [Connecting a Website Form](/help/forms/connect-a-website-form)
- [Orchestrations](/help/orchestrations/overview) — what to do with a submission
- [Managing Contacts](/help/crm/contacts) — where a submission lands
- [Google Analytics 4 workflows](/help/integrations/google-analytics-workflows) — attribution on submissions