### Form Schema and Examples

Source: https://developers.tally.so/api-reference/endpoint/forms/post

Defines the structure and required properties for a Form object, including its status, submission counts, and payment details. Includes example data for a successfully created form.

```APIDOC
components:
  schemas:
    Form:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        workspaceId: { type: string }
        status: { $ref: '#/components/schemas/FormStatus' }
        numberOfSubmissions: { type: integer, format: int64 }
        isClosed: { type: boolean }
        payments:
          type: array
          items:
            type: object
            properties:
              amount: { type: integer, format: int64 }
              currency: { type: string }
        createdAt:
          allOf:
            - type: string
              format: date-time
        updatedAt:
          allOf:
            - type: string
              format: date-time
      refIdentifier: '#/components/schemas/Form'
      requiredProperties:
        - id
        - name
        - workspaceId
        - status
        - numberOfSubmissions
        - isClosed
        - createdAt
        - updatedAt
      examples:
        example:
          value:
            id: <string>
            name: <string>
            workspaceId: <string>
            status: BLANK
            numberOfSubmissions: 123
            isClosed: true
            payments:
              - amount: 123
                currency: <string>
            createdAt: '2023-11-07T05:31:56Z'
            updatedAt: '2023-11-07T05:31:56Z'
    '400':
      _mintlify/placeholder:
        schemaArray:
          - type: any
            description: Invalid request body
        examples: {}
        description: Invalid request body
    '401':
      _mintlify/placeholder:
        schemaArray:
          - type: any
            description: Unauthorized
        examples: {}
        description: Unauthorized
  deprecated: false
  type: path
```

--------------------------------

### Fetch Forms (Default API Version)

Source: https://developers.tally.so/api-reference/versioning

Example request to fetch forms using the default API version tied to the API key. Requires Authorization header.

```bash
curl -X GET 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'
```

--------------------------------

### Configure HTTP MCP Client

Source: https://developers.tally.so/api-reference/mcp

Example JSON configuration for an AI assistant client that directly supports HTTP MCP servers. It specifies the server URL and includes the necessary Authorization header.

```json
{
  "mcpServers": {
    "tally": {
      "type": "http",
      "url": "https://api.tally.so/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}
```

--------------------------------

### Tally API: Creating Forms

Source: https://context7_llms

Guides on creating various types of forms using the Tally API, including empty forms, forms with settings, contact forms, dropdowns, and mentions.

```APIDOC
Create Empty Form:
Endpoint: /api/v1/forms
Method: POST
Description: Creates a new, empty Tally form.
Parameters:
  - title (string, optional): The title of the form.
Returns:
  - form_id (string): The ID of the newly created form.

Create Form with Settings:
Endpoint: /api/v1/forms
Method: POST
Description: Creates a new form with specified settings.
Parameters:
  - title (string, optional): The title of the form.
  - settings (object, optional): Configuration for the form (e.g., theme, privacy).
Returns:
  - form_id (string): The ID of the newly created form.

Create Contact Form:
Endpoint: /api/v1/forms
Method: POST
Description: Creates a form pre-configured as a contact form.
Parameters:
  - title (string, optional): The title of the form.
  - type (string, default: 'contact'): Specifies the form type.
Returns:
  - form_id (string): The ID of the newly created form.

Create Form with Dropdown:
Endpoint: /api/v1/forms
Method: POST
Description: Creates a form that includes a dropdown field.
Parameters:
  - title (string, optional): The title of the form.
  - fields (array, required): An array of field definitions, including dropdowns.
    - type (string): 'dropdown'
    - label (string): Label for the dropdown.
    - options (array): List of options for the dropdown.
Returns:
  - form_id (string): The ID of the newly created form.

Create Form with Mention:
Endpoint: /api/v1/forms
Method: POST
Description: Creates a form that includes a mention field.
Parameters:
  - title (string, optional): The title of the form.
  - fields (array, required): An array of field definitions, including mention fields.
    - type (string): 'mention'
    - label (string): Label for the mention field.
Returns:
  - form_id (string): The ID of the newly created form.
```

--------------------------------

### Tally API Response for Form Creation

Source: https://developers.tally.so/documentation/creating-a-mention

Example of a successful response from the Tally API after creating a form with a mention. It includes details of the newly created form.

```json
{
  "numberOfSubmissions": 0,
  "id": "w4AGDr",
  "name": "Hello @name",
  "workspaceId": "qnGe3Z",
  "organizationId": "kwob3J",
  "status": "PUBLISHED",
  "updatedAt": "2025-01-14T14:01:47.222Z",
  "createdAt": "2025-01-14T14:01:47.222Z",
  "isClosed": false
}
```

--------------------------------

### Example: Create Tally Form with Dropdown using cURL

Source: https://developers.tally.so/documentation/creating-a-dropdown

Demonstrates how to use cURL to send a POST request to the Tally API to create a form with a dropdown menu. Includes setting authorization headers and the JSON payload.

```bash
curl -X POST 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{ \
  "status": "PUBLISHED", \
  "blocks": [ \
    { \
      "uuid": "6ef8675d-33cb-419b-a81e-93982e726f2e", \
      "type": "FORM_TITLE", \
      "groupUuid": "073c835f-7ad4-459c-866d-4108b6b7e2e1", \
      "groupType": "TEXT", \
      "payload": { \
        "title": "Dropdown example", \
        "html": "Dropdown example" \
      } \
    }, \
    { \
      "uuid": "2515b4dd-54e3-4502-afe6-074ad5019b44", \
      "type": "TITLE", \
      "groupUuid": "22a0af81-0117-4931-806f-2b83e374275b", \
      "groupType": "QUESTION", \
      "payload": { \
        "html": "What\'s your favorite color?" \
      } \
    }, \
    { \
        "uuid": "338631d5-64b0-4a55-8219-17658e66196b", \
        "type": "DROPDOWN_OPTION", \
        "groupUuid": "aa64831b-8695-4887-afba-31c07034cd77", \
        "groupType": "DROPDOWN", \
        "payload": { \
            "index": 0, \
            "text": "Red" \
        } \
    }, \
    { \
        "uuid": "4c8fe10a-b07e-407e-9347-f64d73a9ba9a", \
        "type": "DROPDOWN_OPTION", \
        "groupUuid": "aa64831b-8695-4887-afba-31c07034cd77", \
        "groupType": "DROPDOWN", \
        "payload": { \
            "index": 1, \
            "text": "Green" \
        } \
    }, \
    { \
        "uuid": "3bddc101-571b-4f00-aa7a-30ee629441bc", \
        "type": "DROPDOWN_OPTION", \
        "groupUuid": "aa64831b-8695-4887-afba-31c07034cd77", \
        "groupType": "DROPDOWN", \
        "payload": { \
            "index": 2, \
            "text": "Blue" \
        } \
    } \
  ] \
}'
```

--------------------------------

### Forms Response (Default API Version)

Source: https://developers.tally.so/api-reference/versioning

Example JSON response when fetching forms using the default API version. Returns a list of forms directly.

```json
[
  {
    "id": "LmBenY",
    "name": "Test",
    "isNameModifiedByUser": false,
    "workspaceId": "kwob3J",
    "organizationId": "kwob3J",
    "status": "PUBLISHED",
    "hasDraftBlocks": false,
    "numberOfSubmissions": 0,
    "createdAt": "2025-01-28T09:23:24.000Z",
    "updatedAt": "2025-01-28T09:41:22.000Z",
    "index": 0,
    "isClosed": false
  },
  {
    "id": "qnGe3Z",
    "name": "Contact form",
    "isNameModifiedByUser": false,
    "workspaceId": "kwob3J",
    "organizationId": "kwob3J",
    "status": "PUBLISHED",
    "hasDraftBlocks": false,
    "numberOfSubmissions": 7,
    "createdAt": "2025-01-14T09:55:31.000Z",
    "updatedAt": "2025-01-23T13:09:13.000Z",
    "index": 1,
    "isClosed": false
  }
]
```

--------------------------------

### Example: Tally API Response for Created Form

Source: https://developers.tally.so/documentation/creating-a-dropdown

Illustrates the JSON response received from the Tally API upon successful creation of a form. This includes details about the newly created form.

```json
{
  "id": "m2fK5R",
  "name": "Dropdown example",
  "workspaceId": "kb3o5R",
  "organizationId": "atL65s",
  "status": "PUBLISHED",
  "hasDraftBlocks": false,
  "isClosed": false,
  "updatedAt": "2024-12-20T10:34:19.262Z",
  "createdAt": "2024-12-20T10:34:19.262Z"
}
```

--------------------------------

### Configure MCP Client via mcp-remote package

Source: https://developers.tally.so/api-reference/mcp

Example JSON configuration for clients that may not directly support HTTP MCP servers. It uses the `mcp-remote` package via `npx` to connect to the Tally MCP server, passing the URL and headers as arguments.

```json
{
  "mcpServers": {
    "tally": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.tally.so/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY_HERE"
      ]
    }
  }
}
```

--------------------------------

### Tally.so API: GET /forms/{formId}

Source: https://developers.tally.so/api-reference/endpoint/forms/get

Details the Tally.so API endpoint for fetching form data. It specifies the GET request method, the path parameter `formId`, authentication via bearer token, and the JSON response structure. The response schema outlines form properties, settings, and blocks, with an example provided.

```yaml
GET /forms/{formId}
paths:
  path: /forms/{formId}
  method: get
  servers:
    - url: https://api.tally.so
  request:
    security:
      - title: bearerAuth
        parameters:
          query: {}
          header:
            Authorization:
              type: http
              scheme: bearer
          cookie: {}
    parameters:
      path:
        formId:
          schema:
            - type: string
              required: true
              description: The ID of the form to retrieve
      query: {}
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              id:
                allOf:
                  - type: string
              name:
                allOf:
                  - type: string
              workspaceId:
                allOf:
                  - type: string
              status:
                allOf:
                  - $ref: '#/components/schemas/FormStatus'
              numberOfSubmissions:
                allOf:
                  - type: number
              isClosed:
                allOf:
                  - type: boolean
              payments:
                allOf:
                  - type: array
                    items:
                      type: object
                      properties:
                        amount:
                          type: number
                        currency:
                          type: string
              createdAt:
                allOf:
                  - type: string
                    format: date-time
              updatedAt:
                allOf:
                  - type: string
                    format: date-time
              settings:
                allOf:
                  - $ref: '#/components/schemas/FormSettings'
              blocks:
                allOf:
                  - type: array
                    items:
                      type: object
                      required:
                        - uuid
                        - type
                        - groupUuid
                        - groupType
                        - payload
                      properties:
                        uuid:
                          type: string
                          format: uuid
                        type:
                          $ref: '#/components/schemas/BlockType'
                        groupUuid:
                          type: string
                          format: uuid
                        groupType:
                          $ref: '#/components/schemas/BlockType'
                        payload:
                          type: object
            refIdentifier: '#/components/schemas/Form'
            requiredProperties:
              - id
              - name
              - workspaceId
              - status
              - numberOfSubmissions
              - isClosed
              - createdAt
              - updatedAt
        examples:
          example:
            value:
              id: <string>
              name: <string>
              workspaceId: <string>
              status: BLANK
              numberOfSubmissions: 123
              isClosed: true
              payments:
                - amount: 123
                  currency: <string>
              createdAt: '2023-11-07T05:31:56Z'
              updatedAt: '2023-11-07T05:31:56Z'
              settings:
                language: <string>
                isClosed: false
                closeMessageTitle: <string>
                closeMessageDescription: <string>
                closeTimezone: <string>
                closeDate: <string>
                closeTime: <string>
                submissionsLimit: 1
                uniqueSubmissionKey: <string>
                redirectOnCompletion: <string>
                hasSelfEmailNotifications: false
                selfEmailTo: <string>
                selfEmailReplyTo: <string>
                selfEmailSubject: <string>
                selfEmailFromName: <string>
                selfEmailBody: <string>
                hasRespondentEmailNotifications: false
                respondentEmailTo: <string>
                respondentEmailReplyTo: <string>
                respondentEmailSubject: <string>
                respondentEmailFromName: <string>
                respondentEmailBody: <string>
                hasProgressBar: false
                hasPartialSubmissions: false
                pageAutoJump: false
                saveForLater: true
                styles: <string>
                password: <string>
                submissionsDataRetentionDuration: 1
                submissionsDataRetentionUnit: <string>
              blocks:
                - uuid: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                  type: FORM_TITLE
                  groupUuid: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                  groupType: FORM_TITLE

```

--------------------------------

### Fetch Forms (Specific API Version)

Source: https://developers.tally.so/api-reference/versioning

Example request to fetch forms specifying a particular API version using the 'tally-version' header. This is useful for accessing older or newer API behaviors.

```bash
curl -X GET 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-H 'tally-version: 2025-02-01'
```

--------------------------------

### Create Form via Tally API

Source: https://developers.tally.so/documentation/creating-a-form

Demonstrates how to create a new form using the Tally API. This involves sending a POST request to the `/forms` endpoint with a JSON payload specifying form details like title and blocks. Includes example request (curl) and response (JSON).

```bash
curl -X POST 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "6ef8675d-33cb-419b-a81e-93982e726f2e",
      "type": "FORM_TITLE",
      "groupUuid": "073c835f-7ad4-459c-866d-4108b6b7e2e1",
      "groupType": "TEXT",
      "payload": {
        "title": "Test",
        "html": "Test"
      }
    }
  ] 
}'
```

```json
{
  "id": "m2fK5R",
  "name": "Test",
  "workspaceId": "kb3o5R",
  "organizationId": "atL65s",
  "status": "PUBLISHED",
  "hasDraftBlocks": false,
  "isClosed": false,
  "updatedAt": "2024-12-20T10:34:19.262Z",
  "createdAt": "2024-12-20T10:34:19.262Z"
}
```

--------------------------------

### Forms Response (Specific API Version)

Source: https://developers.tally.so/api-reference/versioning

Example JSON response when fetching forms with a specified API version. This version includes pagination metadata and wraps the data in an 'items' key.

```json
{
  "items": [
    {
      "id": "LmBenY",
      "name": "Test",
      "isNameModifiedByUser": false,
      "workspaceId": "kwob3J",
      "organizationId": "kwob3J",
      "status": "PUBLISHED",
      "hasDraftBlocks": false,
      "numberOfSubmissions": 0,
      "createdAt": "2025-01-28T09:23:24.000Z",
      "updatedAt": "2025-01-28T09:41:22.000Z",
      "index": 0,
      "isClosed": false
    },
    {
      "id": "qnGe3Z",
      "name": "Contact form",
      "isNameModifiedByUser": false,
      "workspaceId": "kwob3J",
      "organizationId": "kwob3J",
      "status": "PUBLISHED",
      "hasDraftBlocks": false,
      "numberOfSubmissions": 7,
      "createdAt": "2025-01-14T09:55:31.000Z",
      "updatedAt": "2025-01-23T13:09:13.000Z",
      "index": 1,
      "isClosed": false
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 2,
  "hasMore": false
}
```

--------------------------------

### Tally.so API: GET /webhooks - List Webhooks

Source: https://developers.tally.so/api-reference/endpoint/webhooks/get

Retrieves a list of webhooks configured for your Tally account. Supports pagination using `page` and `limit` query parameters. The response includes details for each webhook, such as its ID, URL, associated form, event types, and status, along with pagination metadata.

```APIDOC
GET /webhooks
  servers:
    - url: https://api.tally.so
  request:
    security:
      - title: bearerAuth
        parameters:
          header:
            Authorization:
              type: http
              scheme: bearer
    parameters:
      query:
        page:
          schema:
            - type: number
              required: false
              description: 'Page number for pagination (default: 1)'
              minimum: 1
        limit:
          schema:
            - type: number
              required: false
              description: 'Number of webhooks per page (default: 25, max: 100)'
              maximum: 100
              minimum: 1
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              webhooks:
                allOf:
                  - type: array
                    description: List of webhooks
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Webhook ID
                        formId:
                          type: string
                          description: Form ID the webhook is attached to
                        url:
                          type: string
                          description: The webhook endpoint URL
                        signingSecret:
                          type: string
                          nullable: true
                          description: Secret used to sign webhook payloads
                        httpHeaders:
                          type: array
                          nullable: true
                          description: Custom HTTP headers to include in webhook requests
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: Header name
                              value:
                                type: string
                                description: Header value
                        eventTypes:
                          type: array
                          description: Types of events this webhook subscribes to
                          items:
                            $ref: '#/components/schemas/EventType'
                        externalSubscriber:
                          type: string
                          nullable: true
                          description: External subscriber identifier
                        isEnabled:
                          type: boolean
                          description: Whether the webhook is enabled
                        lastSyncedAt:
                          type: string
                          format: date-time
                          nullable: true
                          description: When the webhook was last synced
                        createdAt:
                          type: string
                          format: date-time
                          description: When the webhook was created
                        updatedAt:
                          type: string
                          format: date-time
                          description: When the webhook was last updated
              page:
                allOf:
                  - type: number
                    description: Current page number
              limit:
                allOf:
                  - type: number
                    description: Number of webhooks per page
              hasMore:
                allOf:
                  - type: boolean
                    description: Whether there are more pages available
              totalCount:
                allOf:
                  - type: number
                    description: Total number of webhooks
        examples:
          example:
            value:
              webhooks:
                - id: <string>
                  formId: <string>
                  url: <string>
                  signingSecret: <string>
                  httpHeaders:
                    - name: <string>
                      value: <string>
                  eventTypes:
                    - FORM_RESPONSE
                  externalSubscriber: <string>
                  isEnabled: true
                  lastSyncedAt: '2023-11-07T05:31:56Z'
                  createdAt: '2023-11-07T05:31:56Z'
                  updatedAt: '2023-11-07T05:31:56Z'
              page: 123
              limit: 123
              hasMore: true
              totalCount: 123
        description: List of webhooks
    '401':
      _mintlify/placeholder:
        schemaArray:
          - type: any
```

--------------------------------

### Example API Request (PATCH /forms/:id)

Source: https://developers.tally.so/documentation/styling-title-blocks

Demonstrates how to use curl to send a PATCH request to the Tally API to update a form, specifically styling a title block with HTML.

```bash
curl -X PATCH 'https://api.tally.so/forms/:id' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{ \
  "name": "Test", \
  "status": "PUBLISHED", \
  "blocks": [ \
    { \
      "uuid": "6ef8675d-33cb-419b-a81e-93982e726f2e", \
      "type": "FORM_TITLE", \
      "groupUuid": "073c835f-7ad4-459c-866d-4108b6b7e2e1", \
      "groupType": "TEXT", \
      "payload": { \
        "html": "Test", \
        "title": "Test" \
      } \
    }, \
    { \
      "uuid": "48b4cdf3-2c9d-47d3-b8fb-b0ccabc5cd84", \
      "type": "TITLE", \
      "groupUuid": "93034250-5f05-4710-b8e0-5c9145c5b9ea", \
      "groupType": "QUESTION", \
      "payload": { \
        "html": "What'\'s your <span style=\"color: #eb4d4b\"><i><b>name</b></i></span>?" \
      } \
    }, \
    { \
      "uuid": "884ff838-97f9-4ac9-8db1-31aa052df988", \
      "type": "INPUT_TEXT", \
      "groupUuid": "3287d15c-c2b2-4f84-a915-bc57380a4b51", \
      "groupType": "INPUT_TEXT", \
      "payload": { \
        "isRequired": true, \
        "placeholder": "" \
      } \
    } \
  ] \
}'
```

--------------------------------

### List Forms API Endpoint

Source: https://developers.tally.so/api-reference/endpoint/forms/list

Details the GET /forms endpoint for retrieving a paginated list of forms. Includes request parameters, security requirements, and the structure of the JSON response, which contains form items, pagination info, and schema definitions.

```APIDOC
GET /forms
paths:
  path: /forms
  method: get
  servers:
    - url: https://api.tally.so
  request:
    security:
      - title: bearerAuth
        parameters:
          query: {}
          header:
            Authorization:
              type: http
              scheme: bearer
          cookie: {}
    parameters:
      path: {}
      query:
        page:
          schema:
            - type: number
              required: false
              description: 'Page number for pagination (default: 1)'
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              items:
                allOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Form'
              page:
                allOf:
                  - type: number
                    description: Current page number
              limit:
                allOf:
                  - type: number
                    description: Number of items per page
              total:
                allOf:
                  - type: number
                    description: Total number of items
              hasMore:
                allOf:
                  - type: boolean
                    description: Whether there are more pages available
            requiredProperties:
              - items
              - page
              - limit
              - total
              - hasMore
        examples:
          example:
            value:
              items:
                - id: <string>
                  name: <string>
                  workspaceId: <string>
                  status: BLANK
                  numberOfSubmissions: 123
                  isClosed: true
                  payments:
                    - amount: 123
                      currency: <string>
                  createdAt: '2023-11-07T05:31:56Z'
                  updatedAt: '2023-11-07T05:31:56Z'
              page: 123
              limit: 123
              total: 123
              hasMore: true
        description: A paginated list of forms
  deprecated: false
  type: path
components:
  schemas:
    FormStatus:
      type: string
      enum:
        - BLANK
        - DRAFT
        - PUBLISHED
        - DELETED
    Form:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        workspaceId:
          type: string
        status:
          $ref: '#/components/schemas/FormStatus'
        numberOfSubmissions:
          type: number
        isClosed:
          type: boolean
        payments:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
              currency:
                type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - workspaceId
        - status
        - numberOfSubmissions
        - isClosed
        - createdAt
        - updatedAt
```

--------------------------------

### Tally API: Create Form (POST /forms)

Source: https://developers.tally.so/documentation/creating-a-contact-form

This entry documents the Tally API endpoint for programmatically creating new forms. It details the required POST request, including authentication, content type, and the JSON payload structure for defining form properties and individual blocks (e.g., titles, text inputs, email inputs, text areas) with their UUIDs, types, and payload configurations (e.g., `isRequired`, `placeholder`). It also provides an example of a successful API response, including form metadata like ID, name, workspace, and timestamps.

```bash
curl -X POST 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "6ef8675d-33cb-419b-a81e-93982e726f2e",
      "type": "FORM_TITLE",
      "groupUuid": "073c835f-7ad4-459c-866d-4108b6b7e2e1",
      "groupType": "TEXT",
      "payload": {
        "html": "Contact form"
      }
    },
    {
      "uuid": "48b4cdf3-2c9d-47d3-b8fb-b0ccabc5cd84",
      "type": "TITLE",
      "groupUuid": "93034250-5f05-4710-b8e0-5c9145c5b9ea",
      "groupType": "QUESTION",
      "payload": {
        "html": "Name"
      }
    },
    {
      "uuid": "884ff838-97f9-4ac9-8db1-31aa052df988",
      "type": "INPUT_TEXT",
      "groupUuid": "93034250-5f05-4710-b8e0-5c9145c5b9ea",
      "groupType": "QUESTION",
      "payload": {
        "isRequired": true,
        "placeholder": "Enter your name"
      }
    },
    {
      "uuid": "7d9c2e31-b5aa-4c8b-9c2d-123456789abc",
      "type": "TITLE",
      "groupUuid": "3287d15c-c2b2-4f84-a915-bc57380a4b51",
      "groupType": "QUESTION",
      "payload": {
        "html": "Email"
      }
    },
    {
      "uuid": "9b3f5d2a-1c8e-4f7d-b6a9-def012345678",
      "type": "INPUT_EMAIL",
      "groupUuid": "3287d15c-c2b2-4f84-a915-bc57380a4b51",
      "groupType": "QUESTION",
      "payload": {
        "isRequired": true,
        "placeholder": "Enter your email"
      }
    },
    {
      "uuid": "abc12345-6789-def0-1234-56789abcdef0",
      "type": "TITLE",
      "groupUuid": "456789ab-cdef-4321-b8e0-987654321def",
      "groupType": "QUESTION",
      "payload": {
        "html": "Message"
      }
    },
    {
      "uuid": "456789ab-cdef-0123-4567-89abcdef0123",
      "type": "TEXTAREA",
      "groupUuid": "456789ab-cdef-4321-b8e0-987654321def",
      "groupType": "QUESTION",
      "payload": {
        "isRequired": true,
        "placeholder": "Enter your message"
      }
    }
  ]
}'
```

```json
{
  "id": "m2fK5R",
  "name": "Contact form",
  "workspaceId": "kb3o5R",
  "organizationId": "atL65s",
  "status": "PUBLISHED",
  "hasDraftBlocks": false,
  "isClosed": false,
  "updatedAt": "2024-12-20T10:34:19.262Z",
  "createdAt": "2024-12-20T10:34:19.262Z"
}
```

--------------------------------

### Tally API Introduction and Overview

Source: https://context7_llms

Provides fundamental concepts and an overview of Tally's API, including authentication and general usage patterns.

```APIDOC
Introduction:
  - Fundamental concepts of Tally's API.
  - Covers authentication, rate limits, and best practices.

API Keys:
  - Learn how API keys work on Tally.
  - Securely authenticate your requests.

Changelog:
  - Track changes made to the Tally API.
  - Stay updated with new features and improvements.
```

--------------------------------

### Create Tally Form with Settings

Source: https://developers.tally.so/documentation/creating-a-form-with-settings

Demonstrates creating a Tally form with various configurations like language, closing date, submission limits, and custom styling via a POST request to the Tally API. Requires an API key for authorization.

```bash
curl -X POST 'https://api.tally.so/forms' \
-H 'Authorization: Bearer tly-31Aio2vZNKwxGSmaDgutZHLaCg3s7R6c' \
-H 'Content-Type: application/json' \
-d '{ ... }'
```

```json
{
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "ea43ce44-71ae-4e79-b6c2-40e739f61c4b",
      "type": "FORM_TITLE",
      "groupUuid": "36cfc6e4-6c15-495b-a415-be648f3214b6",
      "groupType": "TEXT",
      "payload": {
        "html": "Hello world"
      }
    },
    {
      "uuid": "1ff064ca-d869-48f2-89eb-bba61101385b",
      "type": "TITLE",
      "groupUuid": "aa1fe42e-4ba9-4e15-a63f-fb5f7dd5d5d7",
      "groupType": "QUESTION",
      "payload": {
        "html": "Email"
      }
    },
    {
      "uuid": "3f437d91-9501-4a73-b793-0abd9585d55a",
      "type": "INPUT_EMAIL",
      "groupUuid": "6f34fcbe-4d2e-49ca-94c5-395809e7e9e6",
      "groupType": "INPUT_EMAIL",
      "payload": {
        "isRequired": true,
        "placeholder": ""
      }
    },
    {
      "uuid": "04e62978-23f7-4121-8f9b-6c37359e60aa",
      "type": "TITLE",
      "groupUuid": "4cf183be-7eea-4a7b-ab1e-3caa77995d0d",
      "groupType": "QUESTION",
      "payload": {
        "html": "URL"
      }
    },
    {
      "uuid": "6033c312-df41-4cae-9ee4-b3893d0a8f5a",
      "type": "INPUT_LINK",
      "groupUuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
      "groupType": "INPUT_LINK",
      "payload": {
        "isRequired": true,
        "placeholder": ""
      }
    }
  ],
  "settings": {
    "language": "fr",
    "closeTimezone": "Europe/Paris",
    "closeDate": "2026-01-09",
    "closeTime": "09:41",
    "submissionsLimit": 42,
    "uniqueSubmissionKey": {
      "html": "<span class=\"mention\" data-uuid=\"36d6ef12-d5b0-4491-b675-5c01cb4799a0\">@Email</span>",
      "mentions": [
        {
          "uuid": "36d6ef12-d5b0-4491-b675-5c01cb4799a0",
          "field": {
            "uuid": "6f34fcbe-4d2e-49ca-94c5-395809e7e9e6",
            "type": "INPUT_FIELD",
            "questionType": "INPUT_EMAIL",
            "blockGroupUuid": "6f34fcbe-4d2e-49ca-94c5-395809e7e9e6",
            "title": "Email"
          }
        }
      ]
    },
    "redirectOnCompletion": {
      "html": "<span class=\"mention\" data-uuid=\"42283ab9-9efe-4b58-bac5-b4fbc04ab945\">@URL</span>",
      "mentions": [
        {
          "uuid": "42283ab9-9efe-4b58-bac5-b4fbc04ab945",
          "field": {
            "uuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "type": "INPUT_FIELD",
            "questionType": "INPUT_LINK",
            "blockGroupUuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "title": "URL"
          }
        }
      ]
    },
    "hasSelfEmailNotifications": true,
    "selfEmailTo": {
      "html": "me@company.com",
      "mentions": []
    },
    "selfEmailReplyTo": {
      "html": "hello@company.com",
      "mentions": []
    },
    "selfEmailSubject": null,
    "selfEmailFromName": null,
    "selfEmailBody": {
      "html": "<b>URL:</a> <span class=\"mention\" data-uuid=\"d036b126-f593-417d-b9a7-0a50db496625\">@URL</span>",
      "mentions": [
        {
          "uuid": "d036b126-f593-417d-b9a7-0a50db496625",
          "field": {
            "uuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "type": "INPUT_FIELD",
            "questionType": "INPUT_LINK",
            "blockGroupUuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "title": "URL"
          }
        }
      ]
    },
    "styles": {
      "theme": "CUSTOM",
      "color": {
        "background": "#ffffff",
        "text": "#37352f",
        "accent": "#007aff",
        "buttonBackground": "#007aff",
        "buttonText": "#ffffff"
      },
      "css": ".tally-submit-button svg {\n  display: none;\n}",
      "direction": "ltr"
    }
  }
}
```

--------------------------------

### Field Schema (Partial)

Source: https://developers.tally.so/api-reference/endpoint/forms/post

A partial definition for a generic Field object, indicating the start of its schema definition.

```APIDOC
components:
  schemas:
    Field:
      type: object
      properties:
        uuid: { type: string, format: uuid }
        name: { type: string }
```

--------------------------------

### Example API Response

Source: https://developers.tally.so/documentation/styling-title-blocks

The JSON response received from the Tally API after successfully updating a form, indicating the form's metadata.

```json
{
  "id": "m2fK5R",
  "name": "Test",
  "workspaceId": "kb3o5R",
  "organizationId": "atL65s",
  "status": "PUBLISHED",
  "hasDraftBlocks": false,
  "isClosed": false,
  "updatedAt": "2024-12-20T10:34:19.262Z",
  "createdAt": "2024-12-20T10:34:19.262Z"
}
```

--------------------------------

### Create Workspace API Endpoint

Source: https://developers.tally.so/api-reference/endpoint/workspaces/post

Defines the POST /workspaces endpoint for creating new workspaces. It details the request body schema (requiring a workspace name), authentication methods (Bearer token), and expected responses, including success (201) with workspace details and error codes (400, 401, 403). Includes schema definitions for User and Workspace objects.

```APIDOC
openapi: 3.0.0
info:
  title: Tally.so API
  version: 1.0.0
  description: API for managing workspaces in Tally.so.

servers:
  - url: https://api.tally.so

paths:
  /workspaces:
    post:
      summary: Create Workspace
      description: Creates a new workspace and assigns the authenticated user as a member. Requires a Pro subscription.
      operationId: createWorkspace
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the workspace
              required:
                - name
            examples:
              example:
                value:
                  name: My New Workspace
      responses:
        '201':
          description: Workspace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
              examples:
                successExample:
                  value:
                    id: "ws-12345"
                    name: "My New Workspace"
                    members:
                      - id: "user-abc"
                        firstName: "John"
                        lastName: "Doe"
                        fullName: "John Doe"
                        email: "john.doe@example.com"
                        avatarUrl: "https://example.com/avatar.png"
                        organizationId: "org-xyz"
                        isDeleted: false
                        hasTwoFactorEnabled: true
                        createdAt: "2023-11-07T05:31:56Z"
                        updatedAt: "2023-11-07T05:31:56Z"
                        subscriptionPlan: "PRO"
                    invites:
                      - id: "invite-789"
                        email: "jane.doe@example.com"
                        workspaceIds:
                          - "ws-12345"
                    createdByUserId: "user-abc"
                    createdAt: "2023-11-07T05:31:56Z"
                    updatedAt: "2023-11-07T05:31:56Z"
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "name is required"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Authentication token is missing or invalid"
        '403':
          description: Forbidden - User doesn't have a Pro subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "User does not have a Pro subscription"

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        email:
          type: string
        avatarUrl:
          type: string
          format: uri
          nullable: true
        organizationId:
          type: string
        isDeleted:
          type: boolean
        hasTwoFactorEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        subscriptionPlan:
          type: string
          enum:
            - FREE
            - PRO
            - BUSINESS
    Workspace:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/User'
        invites:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              email:
                type: string
              workspaceIds:
                type: array
                items:
                  type: string
        createdByUserId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - members
        - invites
        - createdByUserId
        - createdAt
        - updatedAt
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

```

--------------------------------

### APIDOC: Get Form Submissions

Source: https://developers.tally.so/api-reference/endpoint/forms/submissions/list

Retrieves a list of form submissions. Supports filtering and pagination. Includes detailed response structures for successful requests and common error codes.

```APIDOC
paths:
  /submissions:
    get:
      summary: List of form submissions
      parameters:
        - in: query
          name: formId
          description: Filter submissions by form ID
          required: false
          schema:
            type: string
        - in: query
          name: page
          description: Page number for pagination
          required: false
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          description: Number of submissions per page
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Successful retrieval of submissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  submissions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        formId:
                          type: string
                        isCompleted:
                          type: boolean
                        submittedAt:
                          type: string
                          format: date-time
                        responses:
                          type: array
                          items:
                            type: object
                            properties:
                              questionId:
                                type: string
                              value:
                                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: any
                description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: any
                description: Forbidden
        '404':
          description: Form not found
          content:
            application/json:
              schema:
                type: any
                description: Form not found
      deprecated: false
      type: path
```

--------------------------------

### List Webhooks

Source: https://developers.tally.so/api-reference/endpoint/webhooks/get

Returns a paginated list of all webhooks across your accessible forms and workspaces.

```APIDOC
API Endpoint: /webhooks

Method: GET

Description:
  Retrieves a paginated list of all webhooks associated with the authenticated user's forms and workspaces.

Parameters:
  (Query Parameters for Pagination - specific parameters not detailed in source)
  - page: The page number to retrieve.
  - limit: The number of items per page.

Returns:
  A JSON object containing a list of webhook objects and pagination metadata.
  Example structure:
  {
    "data": [
      {
        "id": "wh_abc123",
        "url": "https://example.com/webhook",
        "event_types": ["form_submitted", "user_created"],
        "created_at": "2023-10-27T10:00:00Z",
        "workspace_id": "ws_xyz789"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "next_page": "/webhooks?page=2&limit=10"
    }
  }

Error Conditions:
  - 401 Unauthorized: If the user is not authenticated.
  - 403 Forbidden: If the user does not have permission to list webhooks.
```

--------------------------------

### FormSettings Schema

Source: https://developers.tally.so/api-reference/endpoint/forms/post

Details the configuration options for a form, covering language, closing behavior, notification settings, submission limits, and styling.

```APIDOC
components:
  schemas:
    FormSettings:
      type: object
      properties:
        language: { type: string, maxLength: 12, nullable: true }
        isClosed: { type: boolean, default: false }
        closeMessageTitle: { type: string, nullable: true }
        closeMessageDescription: { type: string, nullable: true }
        closeTimezone: { type: string, maxLength: 256, nullable: true }
        closeDate: { type: string, maxLength: 12, nullable: true }
        closeTime: { type: string, maxLength: 12, nullable: true }
        submissionsLimit: { type: integer, format: int64, minimum: 0, nullable: true }
        uniqueSubmissionKey: { type: string, nullable: true }
        redirectOnCompletion: { type: string, nullable: true }
        hasSelfEmailNotifications: { type: boolean, default: false }
        selfEmailTo: { type: string, nullable: true }
        selfEmailReplyTo: { type: string, nullable: true }
        selfEmailSubject: { type: string, nullable: true }
        selfEmailFromName: { type: string, nullable: true }
        selfEmailBody: { type: string, nullable: true }
        hasRespondentEmailNotifications: { type: boolean, default: false }
        respondentEmailTo: { type: string, nullable: true }
        respondentEmailReplyTo: { type: string, nullable: true }
        respondentEmailSubject: { type: string, nullable: true }
        respondentEmailFromName: { type: string, nullable: true }
        respondentEmailBody: { type: string, nullable: true }
        hasProgressBar: { type: boolean, default: false }
        hasPartialSubmissions: { type: boolean, default: false }
        pageAutoJump: { type: boolean, default: false }
        saveForLater: { type: boolean, default: true }
        styles: { type: string, nullable: true }
        password: { type: string, nullable: true }
        submissionsDataRetentionDuration: { type: integer, format: int64, minimum: 0, nullable: true }
        submissionsDataRetentionUnit: { type: string, maxLength: 12, nullable: true }
```