---
name: genzform
description: Build and run GenZform forms, quizzes, surveys and calculators through the GenZform MCP server - create forms from a prompt or a JSON Schema, add script logic, send prefilled links, read typed responses, export results and connect webhooks or Google Sheets. Use when the user asks to create, change or share a GenZform form, or to read, search or export its responses.
---

# GenZform for agents

GenZform hosts forms, quizzes, surveys, polls and calculators. Respondents open a link; you create the form and read the answers through the MCP server. Forms can run JavaScript hooks, so calculators and scored quizzes work without a click-through logic builder.

## Connect

- MCP server (Streamable HTTP, stateless JSON-RPC over POST): `https://genzform.com/api/mcp`
- Interactive clients (Claude, ChatGPT, Cursor): add the URL as a custom connector and sign in with OAuth. Discovery starts from the `WWW-Authenticate` header of a 401.
- Headless agents (n8n, cron, backends): the user creates an API key at `https://genzform.com/dashboard/mcp?tab=api-keys` (shown once, starts with `gzf_sk_`) and you send it on every request:

```
POST https://genzform.com/api/mcp
Authorization: Bearer gzf_sk_...
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_forms","arguments":{}}}
```

No `initialize` handshake or session id is needed for a raw HTTP call. Tool results are one text item holding JSON: `{"success": true, ...}`, or `isError: true` with `{"success": false, "error": "...", ...}`.

## Cost and limits

- Only two calls use GenZform's AI and spend one AI credit each: `create_form` with a `prompt`, and `update_form` with a `prompt`. Everything else is free, including `create_form` with a `schema`.
- Free plan: 20 AI credits a month, 10 forms, 500 responses a month. Pro ($29/month or $278/year): unlimited AI credits, no form cap, 10,000 responses a month. Over the response limit, forms keep collecting up to twice the limit before they stop.
- Page sizes: max 100 rows per call (`list_forms`, `view_form_response`, `search_responses`); `export_responses` returns up to 1,000 rows.

## Identify a form

Every `form` argument accepts the form id (`frm_...`), the URL code (`form-...`) or the full form link. You can act on forms you own and forms you were invited to as a collaborator; `list_forms` lists only forms you own. Archiving and integration changes are owner-only.

## Tools

| Tool | Arguments | Use it to |
|---|---|---|
| `create_form` | `prompt` or `schema`, optional `category` (FORMS, SURVEYS, QUIZ, CALCULATORS, POLLS) | Create a form. With `prompt` GenZform's AI builds it (1 credit). With `schema` it is built directly, no AI. |
| `update_form` | `form`, optional `prompt`, `template_name` (`classic_template` or `typeform_template`), `theme` (`{primaryColor, backgroundColor}` hex), `recaptcha_enabled` | Edit with a prompt (1 credit), or change template, colours or reCAPTCHA (free). An unknown template name is ignored. |
| `list_forms` | `page`, `limit` (≤100, default 10), `search`, `category`, `sort_by` (created_at, updated_at, form_name), `sort_order` | Find forms you own. |
| `get_form` | `form` | Read settings, `form_link`, `edit_link`, response count and the full form JSON (field ids, scripts). |
| `view_form_response` | `form`, `page`, `limit` (≤100), `sort_by`, `sort_order`, `submitted_after`, `submitted_before`, `respondent` | Read responses, filtered by date (ISO 8601, UTC unless an offset is given; `before` is exclusive) or by text in the respondent's email or name. |
| `search_responses` | `query` (2-200 chars), optional `form`, `page`, `limit` (default 20) | Find responses whose email, name or any answer contains the text, in one form or across all forms you own. |
| `export_responses` | `form`, `format` (`csv` default, or `json`) | Export up to 1,000 newest responses. CSV has the dashboard's columns; JSON has one record per response. Check `truncated`. |
| `duplicate_form` | `form`, optional `new_name` | Copy content, theme and settings into a new form. Responses and integrations are not copied. Counts toward the form limit. |
| `archive_form` | `form` | Remove the form from the dashboard; its link stops accepting responses. Same as Delete in the dashboard and not undoable there. Confirm with the user first. |
| `list_integrations` | `form` | List webhooks, Google Sheets, email and analytics integrations with ids (`fi_...`) and status. |
| `add_webhook` | `form`, `url` | POST every new response as JSON to a public http(s) URL. |
| `set_google_sheets_destination` | `form`, optional `account_id`, `spreadsheet_id`, `sheet_name` | Send responses to Google Sheets. Without `spreadsheet_id` a new spreadsheet is created; without `sheet_name` a new worksheet. Replaces the form's existing Sheets destination. |
| `remove_integration` | `form`, `integration_id` | Delete one integration. |
| `send_integration_test` | `form`, `integration_id` | Send sample data to a webhook or Sheets integration now; reports `delivered` and adds an activity-log entry. |
| `connect_integration` | `form`, `provider` (`google_sheets`) | If no Google account is connected, returns `connect_url` for the user to open. |

Form results include `form_link` (share this) and `edit_link` (the owner's editor).

## Recommended flows

**Data collection with typed output (no AI, no credit).** Call `create_form` with a JSON Schema. Each property becomes one field whose id is the property name, on one page, in the Classic template. Read answers with `view_form_response` or `export_responses` with `format: "json"`; each response has `typed_data` in exactly your schema's shape.

**Logic, layout and copy (1 credit).** Call `create_form` with a `prompt` that names what you need: fields, pages, the formula, validation messages, button labels, unique fields. Then call `get_form` to learn the field ids before you build links or read answers. Use `update_form` with a `prompt` for later changes. You cannot send form JSON directly; the prompt is how you change content.

**Personalised links.** Append `?field_id=value` to `form_link` (URL-encode values). Unknown params are ignored by fields but stay available as `{{param}}` in labels.

**Send responses somewhere.** `add_webhook`, then `send_integration_test` with the returned id. Each POST body is `{form_id, form_name, form_url_code, response_id, submitted_at, data}`, where `data` maps field ids to answers as strings. For Google Sheets: `connect_integration`; if it returns `connect_url`, ask the user to open it and approve, then call `set_google_sheets_destination`.

## Schema in, typed JSON out

```json
{
  "type": "object",
  "title": "Workshop sign-up",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "full_name": { "type": "string", "title": "Your name", "maxLength": 80 },
    "seats": { "type": "integer", "minimum": 1, "maximum": 4 },
    "session": { "type": "string", "enum": ["morning", "afternoon"] },
    "start_date": { "type": "string", "format": "date" },
    "newsletter": { "type": "boolean" },
    "topics": { "type": "array", "items": { "type": "string", "enum": ["ai", "design", "sales"] }, "maxItems": 2 }
  },
  "required": ["email", "seats", "session"]
}
```

Supported subset (anything else is rejected with `invalid_schema`):
- Root: `type: "object"`, `properties` (1-50), optional `required`, `title`, `description`, `$schema`, `$id`, `additionalProperties: false`.
- Property names: lowercase letters, digits and underscores, starting with a letter, max 64 chars. Reserved (used by the form link): `locale`, `template_name`, `bg`, `primary`, `preview`, `redirect_status`, `payment_intent`, `payment_intent_client_secret`, `min_height`, `transparent_background`, `hide_title`, `genz_page_url`, `genz_referrer`.
- `string`: `enum` (non-empty, no duplicates), or `format` `"email"` or `"date"` (not both), `minLength`, `maxLength`.
- `number` / `integer`: `minimum`, `maximum`.
- `boolean`.
- `array` of string enums only: `{"type":"array","items":{"type":"string","enum":[...]}}`, `minItems`, `maxItems`.
- `title` and `description` on any property become the field label and help text (default label: the property name, humanised).
- Not supported: nested objects, other array items, `$ref`, `oneOf`/`anyOf`/`allOf`, `const`, `pattern`, `default`, nullable or multi-type properties, other formats.

Field mapping: string enum → radio (≤5 options) or dropdown; email/date → email/date field; string with `maxLength` > 255 → long text; number/integer → number field; boolean → Yes/No radio; array → checkboxes.

Output: `typed_data` contains only schema keys, numbers as numbers, booleans as booleans, dates as `YYYY-MM-DD`, arrays deduplicated, blank optional answers omitted. If a stored answer does not fit (for example the form was edited later), `typed_data` is `null` and `schema_violations` lists `{property, problem, value}`. Typed output exists only for forms created from a schema.

## Form JSON (what `get_form` returns)

```json
{
  "title": { "en": "Cleaning quote" },
  "available_languages": ["en"],
  "pages": [
    {
      "fields": {
        "square_feet": { "type": "number", "label": { "en": "Square feet" }, "required": true },
        "email": { "type": "email", "label": { "en": "Email" }, "unique": true }
      },
      "navigation": { "next_label": { "en": "Get my quote" }, "hide_previous": true }
    }
  ],
  "thank_you_blocks": [{ "type": "content_box", "value": { "en": "<h2>Your quote: ${{total}}</h2>" } }],
  "on_next_page_scripts": "window.on_input_change = function (formData, custom_variables) { ... };"
}
```

- `pages[].fields` is a map: the key is the field id (used in prefill links, scripts and responses).
- Field types: text, email, tel, number, date, time, date_time, dropdown, text_area, rating, rating_scale, checkboxes, radio, selection_cards, content_box, upload, country-select, slider, signature, column_layout.
- Text is a language object (`{"en": "..."}`); languages are en, fr, de and other.
- `{{name}}` in any label or content box shows a field value or custom variable; macros are JavaScript expressions (`{{total > 100 ? "Free delivery" : ""}}`).
- `hidden` on a field is an expression that hides it, e.g. `"{{budget < 1000 ? true : false}}"`.
- Quiz fields carry `answer` (array of correct values), `points` and `explanation`; scores come back in `quiz_score` on each response.

To change any of this, describe the change in an `update_form` prompt and name the exact field ids, labels and messages you want.

## Script hooks

Scripts live in `on_next_page_scripts` and must assign hooks on `window`. Ask for them by name in your prompt.

| Hook | Runs | Returns |
|---|---|---|
| `on_form_init(formData, custom_variables)` | once, before the first page shows | `custom_variables` (seed every `{{variable}}` shown on page 1) |
| `on_input_change(formData, custom_variables, page_index, field_id)` | while typing, about 300 ms after the user pauses | `{ custom_variables, formData }` |
| `on_input_blur(formData, custom_variables, page_index, field_id)` | when a field loses focus | `{ custom_variables, formData }` |
| `on_next_button_click(formData, custom_variables, page_index)` | on Next | `{ can_proceed, custom_variables, page_no, errors? }` |
| `on_form_submit(formData, custom_variables, page_index)` | on Submit | final data, usually `{ ...formData, ...custom_variables }` |

Live calculator on one page:

```js
function quote(formData) {
  return ((parseFloat(formData.square_feet) || 0) * 0.15).toFixed(2);
}
window.on_form_init = function (formData, custom_variables) {
  custom_variables.total = quote(formData); // formData already holds prefilled values
  return custom_variables;
};
window.on_input_change = function (formData, custom_variables) {
  custom_variables.total = quote(formData);
  return { custom_variables: custom_variables, formData: formData };
};
```

Inline validation (the message shows in red under the field; never use `alert()`). `on_next_button_click` also runs on the last page's Submit: return `page_no: page_index + 1` there or the form is never submitted.

```js
window.on_next_button_click = function (formData, custom_variables, page_index) {
  if (page_index === 0 && !(parseFloat(formData.square_feet) > 0)) {
    return { can_proceed: false, errors: { square_feet: "Enter a size above 0" } };
  }
  return { can_proceed: true, custom_variables: custom_variables, page_no: page_index + 1 };
};
```

Values set in `custom_variables` are saved with the response under `response_data.custom_variables`. Scripts run in the respondent's browser; `<script>` tags inside labels never run.

## Other form controls

- **Buttons:** per page, `navigation` can set `next_label`, `previous_label`, `submit_label` and `hide_next`, `hide_previous`, `hide_submit`. Form-level `hideSubmit: true` hides Submit everywhere.
- **No duplicates:** `unique: true` on a text, email or tel field rejects a submission whose value was already used on this form (email and text are compared case-insensitively, phone ignores spaces, dashes, dots and brackets). The respondent sees "An entry with this value has already been submitted." under the field and nothing is saved.
- **Templates:** `classic_template` (pages) or `typeform_template` (one question at a time).

## Prefilled links

`https://genzform.com/f/form-abc123?email=jane%40example.com&full_name=Jane%20Doe&seats=2`

- Keys are field ids (property names for schema forms). A prefill beats field defaults; a respondent's saved answer beats the prefill.
- Dates: `YYYY-MM-DD` or `DD/MM/YYYY`. Booleans from a schema: `true` / `false`. Choice fields take the option `value`; checkboxes take one value per link.
- A calculator shows the right result for prefilled values only if `on_form_init` computes it (not just sets it to 0).
- Respondents can still edit prefilled fields. Don't put secrets in links.

## Attribution

Every response records, when available: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` (from the link's query string), `page_url`, `referrer`, `device` (desktop, mobile, tablet) and `time_zone`. Read them in `response_data.attribution` (`view_form_response`, `search_responses`) or as extra CSV columns. Add `utm_*` params to links you send so you can tell channels apart.

## Responses

`view_form_response` and `search_responses` return rows with `id`, `email`, `name`, `response_data` (`responses: [{form_question_id, value}]`, plus `custom_variables` and `attribution`), `quiz_score`, `created_at`, and `typed_data` for schema forms. `email` and `name` are taken from the form's first email field and a text field whose id or label contains "name"; `respondent` filters on them.

## Errors and how to recover

| You see | Meaning | Do this |
|---|---|---|
| HTTP 401 `unauthorized` | No Bearer token | Send `Authorization: Bearer <OAuth token or gzf_sk_ key>`. |
| HTTP 401 `invalid_token` | Key revoked or wrong, or OAuth token expired | Ask the user for a new key from `/dashboard/mcp`, or re-authorise. |
| `Pass prompt or schema...` | `create_form` got neither | Resend with one of them. |
| `invalid_schema` | Schema outside the subset; `problems` lists each issue | Fix every listed problem, resend. |
| `form_limit_reached` | Free plan has 10 forms | Archive an unused form (with the user's OK) or upgrade (`upgrade_url`). |
| `ai_usage_limit_reached` | No AI credits left this month (`limit`, `current`) | Use `create_form` with a `schema`, wait for the reset, or upgrade. Do not retry the same prompt. |
| `form_not_created` or an AI error, with `ai_response` | The AI declined or failed; no form was kept | Read `ai_response`. Requests that impersonate a brand or collect passwords or card details outside Stripe are refused; don't rephrase to get around it. |
| `Form not found or unauthorized` | Wrong id, or no access | Call `list_forms` and use the returned `id`. |
| `submitted_after and submitted_before must be ISO 8601 dates...` | Bad date filter | Use `2026-11-10` or `2026-11-10T09:00:00Z`. |
| `Only the form owner can ...` | You are a collaborator | Ask the owner. |
| `google_not_connected` (as `error`, or `status` from `connect_integration`) with `connect_url` | No Google account linked | Give the user `connect_url`; after they approve, retry. |
| `Several Google accounts are connected; pass account_id` | Ambiguous account | Pick an `id` from `accounts` and retry. |
| `Webhook URL must ...` | URL not http(s), not public, or unresolvable | Use a public https URL. |
| `Integration not found` | Wrong `integration_id` | Call `list_integrations`. |
| `delivered: false` with `error` | Webhook or sheet rejected the test | Show the error to the user; fix the endpoint, test again. |
| `typed_data: null` with `schema_violations` | That response no longer fits the schema | Use `response_data` for that row. |
| `truncated: true` | More than 1,000 responses | Page through `view_form_response` with date filters for the rest. |

Input that fails a tool's argument rules (for example `limit` above 100) returns a validation error naming the argument; fix it and resend.

## Good practice

- Ask before `archive_form` and before spending credits on several prompt edits in a row.
- After any prompt-based create or update, call `get_form` and check field ids and scripts before sharing the link: every `on_next_button_click` path that should move on returns `page_no: page_index + 1`, and values shown on page 1 are computed in `on_form_init`. If not, send an `update_form` prompt that names the fix.
- Show the user `form_link` and `edit_link` so they can check the form themselves.
