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