Typeform MCP

Return paginated row-level data for a single field in a dataset. Use this tool when the user wants to see individual records (text responses, numeric ratings, true/false answers, etc.) rather than aggregated numbers. ## What this tool does - Returns one row per response for the specified field, with cursor-based pagination. ## Inputs - account_id: required. - form_id XOR audience_id: form_id for the "forms" dataset, audience_id for the "contacts" dataset. Exactly one. - field_id: form field to list values for. Works in "forms" dataset only. - property_id: property to list values for. Required together with audience_id in the "contacts" dataset. - time_range: { start, end } as unix seconds. Required. - pagination: - page_size: Required. Max 100. - cursor: opaque token from a previous response to fetch the next page. Null for first page. - search: free-text ILIKE filter on values. Null for no filter. - filters: cross-field filter conditions. Null for no filtering. - sort: sort order. Null for default (newest first). ## Output - data: array of rows, each with { row_id, timestamp, text }. - summary: { total_count, match_count } : total rows in scope and rows matching search/filters. - pagination: { page_size, cursor, is_last_page }. Pass cursor back to fetch the next page. ## Supported field types - text, number, boolean, choices, dropdown, nps, date, multi_format, transcript. ## Joining answers per respondent - row_id is consistent across fields for the same form. - To reconstruct one respondent's full set of answers: call this tool once per field, then join the resulting rows on row_id.

Lists all accounts the authenticated user is a member of.

## What this tool does Ranks groups of rows by a measure : e.g. "top 5 lead sources by contact count" or "which NPS category has the most responses." Call insights-public_discover first to resolve form_id / audience_id / field_id / property_id and to learn each field's dimensions, measures, filter_type, filter_operators, and filter_values before filtering. ## Use when - User asks for a ranking, "top N", breakdown by category, or "most/least common" answer - User wants rows grouped by one or two dimensions and sorted by a measure - User wants to compare groups/choices/values against each other, not a single rolled-up number ## Also known as top N, ranking, leaderboard, breakdown by category, grouped counts, most common, least common ## Constraints - Provide exactly one of form_id or audience_id : never both, never neither. - dimensions: 1-2 entries. Each name must be a dimension the selected field supports (see insights-public_discover). - Every optional parameter must be sent as null when unset. ## Supported field types - forms dataset: number, nps, scale, boolean, choices, text_list, payment, dropdown, multi_format, matrix, transcript, ranking. - contacts dataset: text_list.

List the workspaces the caller can see, with id, name, form_count, type (private/shared/custom), and account_id. Pair with forms-list_forms to discover forms in a specific workspace. Supports search by name and pagination.

Return the schema of analytics data available for a given scope. Call this BEFORE any analytics query (insights-public_aggregate/timeseries/toplist/list) to learn which datasets exist, which fields are queryable, what measures and dimensions each field supports, and which filters apply. ## Inputs - account_id: required. - form_id XOR audience_id: form_id for form response data, audience_id for contact data. Provide exactly one. ## Output - datasets: array of datasets, each with fields. Each field lists answer_type, measures, dimensions, supported_query_types, and filter operators. ## Resolving a form by name If the user refers to a form by topic/name/description rather than ID, first call forms-public_list_forms with the search parameter set to keywords from the user's message; it returns forms with titles and IDs. If multiple match, ask the user which form they mean before proceeding.

Retrieve a form. Always call get_form before patch_form so you are working from the current state. ## Parameters - id: The form ID (required) - view: one of - "skeleton" : id, title, field refs+types+titles, thankyou_screens, and welcome_screen. Container fields include their nested children inline under "fields", so the agent sees nested refs without drilling. Cheapest read. - "fields" : drill-down into specific fields. Requires "refs" (list of field refs, max 50). Looks up refs at any depth. Returns the same per-field shape as "full" but only for the requested refs, plus a "missing" array for refs not found. - "full" (default) : the complete form including settings, theme, logic. Use sparingly; this is the most expensive read. - refs: list of field refs (only used when view="fields"). Max 50 per call. Typical workflow: skeleton to find the field, fields to read its details, then patch_form to edit it.

## What this tool does Computes aggregate measures (counts, averages, sums, NPS scores, and more) for a single field or an entire dataset. Call insights-public_discover first to resolve form_id / audience_id / field_id / property_id and to learn each field's filter_type, filter_operators, and filter_values before filtering. ## Use when - User asks for summary statistics, totals, averages, counts, or scores - User wants aggregated data rather than individual rows - User asks about NPS score, response count, average rating, or similar rolled-up metrics ## Also known as summary statistics, totals, counts, averages, sums, NPS scores, aggregate analytics, rolled-up metrics ## Constraints - Provide exactly one of form_id or audience_id : never both, never neither. - Every optional parameter must be sent as null when unset. ## Supported field types - forms dataset: text, number, scale, boolean, choices, dropdown, nps, date, multi_format, transcript, payment, matrix, ranking. - contacts dataset: text, text_list, number.

List forms owned by your user. ## Use cases - Browse all forms in your account - Search for forms by title - Filter forms by workspace - Paginate through large form collections ## Parameters - search: Filter forms by title (partial match, optional) - page: Page number starting from 1 (default: 1) - page_size: Number of forms per page (default: 10, max: 200) - sort_by: Sort field - "created_at", "title", or "last_updated_at" (default: "created_at") - order_by: Sort order - "asc" or "desc" (default: "desc") - workspace_id: Filter by workspace ID (optional) ## Output Returns paginated list of forms with total count and form metadata.

## What this tool does Computes measures bucketed over time for a single field or an entire dataset. Call insights-public_discover first to resolve form_id / audience_id / field_id / property_id and to learn each field's filter_type, filter_operators, and filter_values before filtering. ## Use when - User asks how responses, counts, scores, or averages changed over time - User wants a trend, chart, or time series of any metric - User asks about monthly/weekly/daily breakdowns of responses or scores ## Also known as trend, time series, time-series, over time, by month, by week, by day, timeline, chart data, historical data ## Constraints - Provide exactly one of form_id or audience_id : never both, never neither. - Every optional parameter must be sent as null when unset. ## Supported field types - forms dataset: text, number, scale, boolean, choices, dropdown, nps, date, multi_format, transcript, payment, matrix, ranking. - contacts dataset: text, text_list, number.

Commit a validated batch of patch operations to a form draft. Must be preceded by forms-public_validate_patch; pass the same ops plus its validation_token. If this call fails, re-validate for a fresh token. On CONCURRENT_REQUESTS_CONFLICT: discard the token, re-read with forms-public_get_form, re-validate, and retry. Changes land on the draft only; a published form needs forms-public_publish_form for them to go live. When reporting success to the user, describe what changed rather than quoting patch IDs or version numbers unless they ask. ## Prerequisites - form_id: Required. Call forms-public_list_forms to find it, or use the id returned by forms-public_create_form. - account_id: Required. Call accounts-list_accounts to obtain this value if not already known. ### Parameters - account_id: Account ID (required) - form_id: The form ID (required) - ops: The same ops passed to forms-public_validate_patch (required) - validation_token: The token returned by forms-public_validate_patch (required)

Get a single contact by ID with property metadata included. Use this tool when you need to fetch a specific contact and want property names/types without a separate API call. ## What this tool does - Returns a single contact with all its properties - Property metadata (name, type, template_id) is automatically included - No need to call list_contacts_database_properties separately ## Inputs - contact_id: The UUID of the contact to fetch ## Output - id: Contact UUID - identifier: Primary identifier value (e.g., email address) - properties: Array of properties, each with: - property_id: The property UUID - value: The property value - name: Human-readable property name (e.g., "Email", "Name") - type: Property type (e.g., "email", "short_text", "number") - template_id: Standard property template ID (null for custom properties)

Create a new Typeform form. ## Use cases - Create a blank form to start building a survey or quiz - Create a form in a specific workspace ## Parameters - account_id: Account ID (required) - title: The title of the form (required) - workspace: Workspace href URL, e.g. "https://api.typeform.com/workspaces/abc123" (required) ## Output Returns the created form with its ID, title, workspace, theme, and other metadata. The form is created as unpublished (empty, no content). ## After creating a form After calling this tool, respond with this conversational format: Done : I've created a blank Typeform titled "{title}" in your workspace. One thing to flag: the current version of the Typeform connector can create the form, but it can't add questions or content to it yet : so right now it's empty. To add content, open it in the builder: 👉 Open in the builder: https://admin.typeform.com/form/{form_id}/create The fastest way to build it out is with Typeform AI, right inside the builder. Once you're in, start with Typeform AI and paste this prompt: {Generate a detailed prompt here as a separate paragraph based on what the user described: form type, purpose, key fields. Keep it clear and actionable.} That'll generate the questions, logic, and screens in a few seconds. Want me to tailor the prompt to a specific audience or adjust the fields first? Do NOT provide the public form URL (the form is empty and unpublished). Do NOT suggest adding fields via subsequent API calls : that capability does not exist yet.

List contacts from the user's Contacts database. Use this tool when the user wants to see, search, or find contacts. ## What this tool does - Returns contacts matching the specified criteria with pagination. ## Inputs - segment_id: a saved list ID, or null. If provided, uses the list's filters and sort. - filters: filter criteria, or null for no filtering. Only used when segment_id is null. - sort: sort order, or null for newest first. Only used when segment_id is null. - page: page number, starting at 1. - page_size: results per page. ## Output - total_count: Total contacts matching the criteria. - items: An array of contacts matching the criteria. Each includes its id, identifier (value that uniquely identifies the contact) and an array of associated contact properties. ## Default pagination - page=1, page_size=25. ## Understanding Filters ### Structure - Filters use a two-level group structure: - Root: operator (and/or) + filter_groups array - Each filter_group: operator (and/or) + filters array - Each filter: property_id, operator, value, negate ### Semantics: - Root operator=and: contact must match ALL groups - Root operator=or: contact must match ANY group - Group operator=and: ALL filters in the group must match - Group operator=or: ANY filter in the group must match ### Filter operators by property type - Text (email, short_text, long_text, phone_number, code): equals, starts_with, ends_with, contains, empty, any_of - Number: equals, greater_than, less_than, empty - Timestamp: equals, greater_than, less_than, empty - Select (single_select, multi_select, text_list): equals, contains, empty

Delete/remove a form based on its ID. ## Use cases - Remove a form that is no longer needed - Clean up test forms ## Parameters - id: The form ID to delete (required) ## Output Returns empty response on success.

Get a trigger of an automation (workflow/flow) by its ID. Returns the working state (published baseline + any pending draft operations). The trigger_type determines which kind of trigger to fetch. ## Prerequisites - `account_id` : obtain via `accounts-list_accounts`. - `trigger_id` and `trigger_type` : obtain via `public_list_automations` (each automation's `triggers[].id`/`.type`) or from the `public_create_automation` output.

Make the form live and publicly accessible. Each call promotes the draft and snapshots a new version, so only call when the user explicitly wants to go live; never to re-confirm. Drafts save automatically, so this is not a save. Resolve form names to IDs with forms-public_list_forms. ## Prerequisites - form_id: Required. Call forms-public_list_forms to find it, or use the id returned by forms-public_create_form. - account_id: Required. Call accounts-list_accounts to obtain this value if not already known. ### Parameters - account_id: Account ID (required) - form_id: Form ID to publish (required) ### Errors - PAYMENT_REQUIRED: plan-gated features are blocking. Tell the user which, in plain language, and suggest upgrading or removing them. ### Output form_id, version, share_url. An empty share_url still means success; fetch the URL via forms-public_get_form.

Create a new contact in the user's Contacts database. Use this tool when the user wants to add, create, or register a new contact. ## What this tool does - Creates a single contact with the provided properties. ## Inputs - properties: Contact field values as property ID and value pairs. - At least one identifying property (e.g. email) is required. ## Output - The created contact. Includes its id, identifier (value that uniquely identifies the contact) and an array of associated contact properties. ## Property Value Formats When providing property values, use the following formats based on property type: - Text (email, short_text, long_text, phone_number, code): {"type": "text", "text": "value"} - Number: {"type": "number", "number": 42.0} - Timestamp: {"type": "timestamp", "timestamp": "2024-01-15T00:00:00Z"} - Select (single_select, multi_select, text_list): {"type": "text_list", "text_list": ["option1"]}

Duplicate an existing Typeform form. Creates a new form that is a copy of the source form. The new form is unpublished regardless of the source form's published state. ## Prerequisites - form_id: Required. Call forms-public_list_forms to find it, or use the id returned by forms-public_create_form. - account_id: Required. Call accounts-list_accounts to obtain this value if not already known. ## What is preserved - All fields, logic, variables, hidden fields - Theme, settings, welcome/thank-you/consent screens, outcome, CUI settings - Attachments, layouts, and media (re-referenced to the new form) - Knowledge entries (duplicated with remapped IDs) - Translations/messages (best-effort; may be absent if copying fails) ## What is reset - New form ID and timestamps (CreatedAt, UpdatedAt) - PayPal merchant_id and Google Calendar calendar_id are cleared - Email consent notification config reset to account default - Form is always created as unpublished (IsPublic = false) ## Parameters - account_id: Account ID (required) - form_id: ID of the source form to duplicate (required) - title: Title for the new form. Omit to inherit the source form's title. - workspace_id: Workspace for the new form. Always ask the user which workspace to duplicate into before calling this tool.

Delete a contact from the Contacts database. ## Prerequisites - Call list_contacts first to find the contact ID you want to delete. ## Input - contact_id (required): The ID of the contact to delete ## Output format Confirm the deletion was successful.

Validate a batch of patch operations against a form draft without persisting anything. IMPORTANT: This does not save. You MUST call forms-public_patch_form with the returned validation_token immediately after to persist. If side_effects is non-empty, explain them to the user in plain language and warn them before committing. Ops run sequentially in memory, so order add_field / add_ending before any add_logic ops that reference them; anything not committed and not earlier in the batch does not exist yet. First failure stops validation and returns no token. ## Prerequisites - form_id: Required. Call forms-public_list_forms to find it, or use the id returned by forms-public_create_form. - account_id: Required. Call accounts-list_accounts to obtain this value if not already known. ### Parameters - account_id: Account ID (required) - form_id: The form ID (required) - ops: The batch of patch operations to validate (required) ### Common mistakes - Choice conditions: condition.value must be a choice REF, not a label. Read refs via forms-public_get_form(view=fields) first. - add_ending: set screen_ref explicitly if add_logic in the same batch references it; omit for an auto-generated ref. Call forms-public_get_capabilities for supported types, validation keys, and error codes.

Update an existing contact in the user's Contacts database. Use this tool when the user wants to modify, change, or update a contact's information. ## What this tool does - Updates the contact with only the properties provided; others remain unchanged. ## Inputs - contact_id: The ID of the contact to update. - properties: Contact field values as property ID and value pairs. Only include fields to change. ## Output - The updated contact. ## Property Value Formats When providing property values, use the following formats based on property type: - Text (email, short_text, long_text, phone_number, code): {"type": "text", "text": "value"} - Number: {"type": "number", "number": 42.0} - Timestamp: {"type": "timestamp", "timestamp": "2024-01-15T00:00:00Z"} - Select (single_select, multi_select, text_list): {"type": "text_list", "text_list": ["option1"]}

Return the capability matrix for the Typeform form editing tools. Call once before authoring any ops, and use the response instead of guessing field types, op names, or validation keys. ### Response fields - supported_types: field types accepted by forms-public_patch_form - container_types: types that accept nested fields. Containers have no settable property keys and do not appear in property_keys_by_type. Their children are managed via add_field (set parent_ref to the container's ref), move_field (move an existing field into the container via parent_ref, or reorder within it via before_ref), and delete_field : not through a properties bag. - choice_bearing_types / choices_required_on_add: types that carry or require choices - validation_keys_by_type: accepted validation keys per field type - property_keys_by_type: accepted property keys per field type - patch_ops: op verbs grouped by domain (field / logic) - condition_ops_by_type: valid ops per field type. Use this to author logic rules. - logic_actions: accepted action types for logic rules - error_codes / side_effect_codes / concurrency_codes: with recovery hints

Remove one or more steps from an existing automation (workflow/flow) ## Prerequisites - `account_id` : obtain via `accounts-list_accounts`. - `automation_id` : obtain via `public_list_automations`. - `step_ids` : obtain via `public_get_automation` (`workflow.steps[].id`).

Patch a trigger of an automation (workflow/flow) via JSON Patch operations (add/replace/remove). See the input schema for the "value" field's rules and for concrete examples. Prefer add/remove over replace : they're safer and more precise. ## Prerequisites - `account_id` : obtain via `accounts-list_accounts`. - `trigger_id` and `trigger_type` : obtain via `public_list_automations` (each automation's `triggers[].id`/`.type`) or from the `public_create_automation` output. - `last_patch_id` : obtain via `public_get_trigger`. ### Contact trigger paths - /type, /condition - /list_ids : only for CONTACT_ADDED_TO_LIST / CONTACT_REMOVED_FROM_LIST - /filter_list_ids : only for CONTACT_CREATED / CONTACT_PROPERTY_UPDATED (optional AND-filter) Switching /type requires removing the old type's fields (e.g. ADDED_TO_LIST → CREATED removes /list_ids). ### Form trigger paths /workspace_id, /form_id, /condition, /filter_ending_refs, /filter_partial_submit_refs ## Condition two-slot layout (CRITICAL) The condition root is either null or {"op": "and", "vars": [slot0, slot1]} with exactly 2 vars. - slot0 (path /condition/vars/0): reserved for "becomes"/"changed" conditions. Use {"op": "always"} as a placeholder when unused. - slot1 (path /condition/vars/1): reserved for every other condition type (is, is_not, equal, not_equal, begins_with, ends_with, contains, not_contains, is_any_of). Use {"op": "always"} as a placeholder when unused. - Never put becomes/changed in slot1, never put other types in slot0, never patch /condition/vars directly. - Nest multiple conditions within a slot under "and"/"or". - If condition is null, "replace" /condition with the full root (both slots). To clear all conditions, "remove" /condition. ## Operators - Comparison ops take exactly 2 vars: [field_var, value_var]. - "changed": value_var is {"type": "constant", "value": ""}. - "is_any_of": value_var must be a JSON array, e.g. {"type": "choice", "value": ["subscribed", "unsubscribed"]}. - The field var value is always the field "ref" (from the form or headless form), never the field "id". - "becomes" and "changed" are only valid for CONTACT_PROPERTY_UPDATED triggers. - Numeric comparisons (lower_than, lower_equal_than, greater_than, greater_equal_than): value_var must be a JSON number, e.g. {"type": "constant", "value": 3} : never the string "3". ### Ops by property type - multiple_choice: value_var uses {"type": "choice", ...} (not "constant"). Supported: is, is_not, becomes, changed, is_any_of. - number: equal, not_equal, lower_than, lower_equal_than, greater_than, greater_equal_than, is_any_of (plus becomes, changed for CONTACT_PROPERTY_UPDATED). Range comparisons take a JSON number operand. - text (default): equal, not_equal, begins_with, ends_with, contains, not_contains, is_any_of (plus becomes, changed for CONTACT_PROPERTY_UPDATED). Compose filters via is_any_of/and/or before treating something as unsupported.

Move an existing step to a new position in an automation (workflow/flow) in one call. The step is relocated, not recreated: its id and full configuration are preserved. ## Prerequisites - `account_id` : obtain via `accounts-list_accounts`. - `automation_id` : obtain via `public_list_automations`. - `step_id` and `after_step_id` : obtain via `public_get_automation` (`workflow.steps[].id`). ## Positioning - position: "entrypoint" (step becomes first; previous entrypoint becomes its successor) | "tail" (step becomes last) | "after" (placed immediately after after_step_id). - after_step_id: required only for "after". Id of the step to follow; must not equal step_id. null for "entrypoint"/"tail". - No "before" position: to move before step X, use "entrypoint" if X is the entrypoint, else "after" with after_step_id set to the step whose next_ids contains X.

Get detailed properties of a specific contacts list (segment). Use this tool to inspect a list before performing operations like deletion, or to understand the list's configuration. ## What this tool does - Retrieves a list's metadata (ID, name, timestamps) ## Input - list_id (required): The ID of the contacts list to retrieve ## Output - id: The list's unique identifier - name: The list's human-readable name - created_at: When the list was created (ISO 8601 timestamp) - updated_at: When the list was last modified (ISO 8601 timestamp) ## Common Use Cases - Confirm list details before deletion: "Show me details for list abc-123 before I delete it" - Review list metadata: "What is the name of list xyz-456?"

Get automation (workflow/flow) by its ID. Returns the working state (published baseline + any pending draft operations). ## Prerequisites - `account_id` : obtain via `accounts-list_accounts`. - `automation_id` : obtain via `public_list_automations`. ## Output - workflow: - id - name - status: DRAFT | ACTIVE | PAUSED - entrypoint_id: ID of the first step to execute - steps: Array of step objects - id - type: DELAY | SEND_EMAIL | SEND_WEBHOOK | SEND_TO_INTEGRATION | TERMINATE - next_ids: Downstream step IDs - triggers: Trigger associations (id, type, enabled) - triggered: Total run count - last_patch_id: Pass as last_patch_id on the next patch

Update the form title. Takes effect immediately on the live form - no publish needed. ## Prerequisites - form_id: Required. Call forms-public_list_forms to find it, or use the id returned by forms-public_create_form. - account_id: Required. Call accounts-list_accounts to obtain this value if not already known.

List all automations (workflows/flows) for the authenticated account. ## Prerequisites - `account_id` : obtain via `accounts-list_accounts`. ## Use cases - Find an automation by name before inspecting or updating it - Discover which automations exist for the account - Get automation IDs needed by other tools (get_automation, publish_automation, pause_automation)