tally-forms

name	tally-forms
description	Create and manage Tally.so forms programmatically using the Tally API. Full coverage of forms, submissions, workspaces, organizations, webhooks, and users endpoints.

Tally Forms Skill

Create and manage Tally.so forms, submissions, workspaces, webhooks, and organizations via their REST API.

Setup

1. Get an API key at tally.so/settings/api-keys (starts with tly-)
2. Set the environment variable:

   export TALLY_API_KEY="tly-your-key-here"
   

API Basics

• Base URL: https://api.tally.so
• Auth header: Authorization: Bearer <TALLY_API_KEY>
• Rate limit: 100 requests/minute
• Content-Type: application/json

How to Use This Skill

When the user wants to create or modify a form:

1. Read reference/blocks.md to understand block types and the 3-block question pattern (QUESTION + TITLE + input)
2. Read reference/forms.md for the POST/PATCH endpoints
3. Read docs/guides.md for worked examples (contact forms, dropdowns, mentions, settings, styling)
4. Key rule: PATCH /forms/:id replaces the entire blocks array — always GET first, append new blocks, then PATCH

When the user wants to fetch or manage submissions:

1. Read reference/submissions.md for LIST/GET/DELETE endpoints
2. Supports filtering by date range, field values, and cursor-based pagination
3. See docs/guides.md > "Fetching Form Submissions" for response structure

When the user wants to set up webhooks:

1. Read reference/webhooks.md for CRUD + event listing/retry
2. Only event type is FORM_RESPONSE (fires on new submission)
3. Webhook URLs must be HTTPS; respond with 2xx within 30 seconds

When the user wants to manage workspaces or organizations:

1. Read reference/workspaces.md for workspace CRUD
2. Read reference/organizations.md for user management and invites
3. Use GET /users/me (see reference/users.md) to get the current user's organization ID

Running scripts:

Each endpoint group has a standalone Python script in scripts/:

python scripts/users.py                    # Verify API key, get user info
python scripts/forms.py                    # List, create, update, delete forms
python scripts/submissions.py <form_id>    # List submissions for a form
python scripts/workspaces.py               # List workspaces
python scripts/webhooks.py <form_id>       # Manage webhooks
python scripts/organizations.py <org_id>   # List org users and invites

Key Concepts

• Blocks are the building units of forms. Every form is an ordered array of blocks.
• Question pattern: 3 blocks sharing a groupUuid — QUESTION (container), TITLE (label), input block (e.g. INPUT_TEXT, INPUT_EMAIL, DROPDOWN)
• Choice nesting: DROPDOWN_OPTION, MULTIPLE_CHOICE_OPTION, CHECKBOX blocks use the container block's uuid as their groupUuid
• Mentions: Dynamic field references in HTML using <span class="mention" data-uuid="...">@fieldName</span> with a mentions array
• Form statuses: BLANK, DRAFT, PUBLISHED, DELETED
• Hidden fields: Populated via URL query params (?name=John)

File Reference

Path	What it contains
reference/forms.md	Forms LIST, GET, POST, PATCH, DELETE + settings object
reference/submissions.md	Submissions LIST (filters, pagination), GET, DELETE + field value types
reference/workspaces.md	Workspaces CRUD
reference/organizations.md	Org users (list, remove) and invites (list, create, cancel)
reference/webhooks.md	Webhooks CRUD + event listing, retry, payload format
reference/users.md	GET /users/me
reference/blocks.md	All 44+ block types, payload fields, nesting rules, examples
scripts/*.py	Standalone runnable scripts for each endpoint group
docs/guides.md	Step-by-step how-to guides from official Tally documentation