🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Tally
πŸ¦€ ClawHub

Tally

by @byungkyu

Tally API integration with managed OAuth. Manage forms, submissions, workspaces, webhooks, organization users, and organization invites. All write operations...

Versionv1.0.4
Downloads3,945
Stars⭐ 3
#requires-paid-service#requires-oauth-token#requires-sensitive-credentials#clawhub
TERMINAL
clawhub install tally-api

πŸ“– About This Skill

name: tally description: | Tally API integration with managed OAuth. Manage forms, submissions, workspaces, and webhooks. Use this skill when users want to create or manage Tally forms, retrieve form submissions, or work with workspaces. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key. metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY

Tally

Access the Tally API with managed OAuth authentication. Manage forms, submissions, workspaces, and webhooks for your Tally account.

Quick Start

# List your forms
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/tally/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('User-Agent', 'Maton/1.0')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/tally/{native-api-path}

Maton proxies requests to api.tally.so and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header and the User Agent header:

Authorization: Bearer $MATON_API_KEY
User-Agent: Maton/1.0

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key

Connection Management

Manage your Tally OAuth connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=tally&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'tally'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response: 

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T21:00:31.222600Z",
    "last_updated_time": "2026-02-07T21:00:37.821240Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "tally",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Tally connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/tally/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

  • Access is scoped to forms, submissions, workspaces, and webhooks within the connected Tally account.
  • All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

    • API Reference

    User

    #### Get Current User

    GET /tally/users/me

    Response: 

    {
  "id": "w2lBkb",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "organizationId": "n0Ze8Q",
  "subscriptionPlan": "FREE",
  "createdAt": "2026-02-07T20:58:54.000Z",
  "updatedAt": "2026-02-07T22:50:35.000Z"
}

    Forms

    #### List Forms

    GET /tally/forms

    Query Parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 50)

    • Response: 

    {
  "items": [
    {
      "id": "GxdRaQ",
      "name": "Contact Form",
      "workspaceId": "3jW9Q1",
      "organizationId": "n0Ze8Q",
      "status": "PUBLISHED",
      "hasDraftBlocks": false,
      "numberOfSubmissions": 42,
      "createdAt": "2026-02-09T08:36:00.000Z",
      "updatedAt": "2026-02-09T08:36:17.000Z",
      "isClosed": false
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "hasMore": false
}

    #### Get Form

    GET /tally/forms/{formId}

    Response: 

    {
  "id": "GxdRaQ",
  "name": "Contact Form",
  "workspaceId": "3jW9Q1",
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "type": "FORM_TITLE",
      "groupUuid": "22222222-2222-2222-2222-222222222222",
      "groupType": "FORM_TITLE",
      "payload": {}
    },
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "type": "INPUT_TEXT",
      "groupUuid": "44444444-4444-4444-4444-444444444444",
      "groupType": "INPUT_TEXT",
      "payload": {}
    }
  ],
  "settings": null
}

    #### Create Form

    POST /tally/forms
Content-Type: application/json
    {
  "status": "DRAFT",
  "workspaceId": "3jW9Q1",
  "blocks": [
    {
      "type": "FORM_TITLE",
      "uuid": "11111111-1111-1111-1111-111111111111",
      "groupUuid": "22222222-2222-2222-2222-222222222222",
      "groupType": "FORM_TITLE",
      "title": "My Form",
      "payload": {}
    },
    {
      "type": "INPUT_TEXT",
      "uuid": "33333333-3333-3333-3333-333333333333",
      "groupUuid": "44444444-4444-4444-4444-444444444444",
      "groupType": "INPUT_TEXT",
      "title": "Your name",
      "payload": {}
    }
  ]
}

    Block Types:

  • FORM_TITLE - Form title block
  • INPUT_TEXT - Single-line text input
  • INPUT_EMAIL - Email input
  • INPUT_NUMBER - Number input
  • INPUT_PHONE_NUMBER - Phone number input
  • INPUT_DATE - Date picker
  • INPUT_TIME - Time picker
  • INPUT_LINK - URL input
  • TEXTAREA - Multi-line text input
  • MULTIPLE_CHOICE - Radio buttons
  • CHECKBOXES - Checkbox group
  • DROPDOWN - Dropdown select
  • LINEAR_SCALE - Scale rating
  • RATING - Star rating
  • FILE_UPLOAD - File upload
  • SIGNATURE - Signature field
  • PAYMENT - Payment field
  • HIDDEN_FIELDS - Hidden fields

    • Note: Block uuid and groupUuid must be valid UUIDs (GUIDs).

    #### Update Form

    PATCH /tally/forms/{formId}
Content-Type: application/json
    {
  "name": "Updated Form Name",
  "status": "PUBLISHED"
}

    Status Values:

  • DRAFT - Form is a draft
  • PUBLISHED - Form is live

    • #### Delete Form

    DELETE /tally/forms/{formId}

    Moves the form to trash.

    Form Questions

    #### List Questions

    GET /tally/forms/{formId}/questions

    Response: 

    {
  "questions": [
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "type": "INPUT_TEXT",
      "title": "Your name"
    }
  ],
  "hasResponses": true
}

    Form Submissions

    #### List Submissions

    GET /tally/forms/{formId}/submissions

    Query Parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 50)
  • startDate - Filter by start date (ISO 8601)
  • endDate - Filter by end date (ISO 8601)
  • afterId - Get submissions after this ID (cursor pagination)

    • Response: 

    {
  "page": 1,
  "limit": 50,
  "hasMore": false,
  "totalNumberOfSubmissionsPerFilter": {
    "all": 42,
    "completed": 40,
    "partial": 2
  },
  "questions": [
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "type": "INPUT_TEXT",
      "title": "Your name"
    }
  ],
  "submissions": [
    {
      "id": "sub123",
      "respondentId": "resp456",
      "formId": "GxdRaQ",
      "createdAt": "2026-02-09T10:00:00.000Z",
      "isCompleted": true,
      "responses": [
        {
          "questionId": "33333333-3333-3333-3333-333333333333",
          "value": "John Doe"
        }
      ]
    }
  ]
}

    #### Get Submission

    GET /tally/forms/{formId}/submissions/{submissionId}

    #### Delete Submission

    DELETE /tally/forms/{formId}/submissions/{submissionId}

    Workspaces

    #### List Workspaces

    GET /tally/workspaces

    Response: 

    {
  "items": [
    {
      "id": "3jW9Q1",
      "name": "My Workspace",
      "createdByUserId": "w2lBkb",
      "createdAt": "2026-02-09T08:35:53.000Z",
      "updatedAt": "2026-02-09T08:35:53.000Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "hasMore": false
}

    #### Get Workspace

    GET /tally/workspaces/{workspaceId}

    Response: 

    {
  "id": "3jW9Q1",
  "name": "My Workspace",
  "createdByUserId": "w2lBkb",
  "createdAt": "2026-02-09T08:35:53.000Z",
  "members": [
    {
      "id": "w2lBkb",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com"
    }
  ]
}

    #### Create Workspace

    POST /tally/workspaces
Content-Type: application/json
    {
  "name": "New Workspace"
}

    Note: Creating workspaces requires a Pro subscription.

    #### Update Workspace

    PATCH /tally/workspaces/{workspaceId}
Content-Type: application/json
    {
  "name": "Updated Workspace Name"
}

    #### Delete Workspace

    DELETE /tally/workspaces/{workspaceId}

    Moves the workspace and all its forms to trash.

    Organization Users

    #### List Users

    GET /tally/organizations/{organizationId}/users

    Response: 

    [
  {
    "id": "w2lBkb",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "createdAt": "2026-02-07T20:58:54.000Z"
  }
]

    #### Remove User

    DELETE /tally/organizations/{organizationId}/users/{userId}

    Organization Invites

    #### List Invites

    GET /tally/organizations/{organizationId}/invites

    #### Create Invite

    POST /tally/organizations/{organizationId}/invites
Content-Type: application/json
    {
  "email": "newuser@example.com",
  "workspaceIds": ["3jW9Q1"]
}

    #### Cancel Invite

    DELETE /tally/organizations/{organizationId}/invites/{inviteId}

    Webhooks

    #### List Webhooks

    GET /tally/webhooks

    Note: Listing webhooks may require specific permissions.

    #### Create Webhook

    POST /tally/webhooks
Content-Type: application/json
    {
  "formId": "GxdRaQ",
  "url": "https://your-endpoint.com/webhook",
  "eventTypes": ["FORM_RESPONSE"]
}

    Webhook Event Types:

  • FORM_RESPONSE - Triggered when a new form response is submitted

    • #### Update Webhook

    PATCH /tally/webhooks/{webhookId}
Content-Type: application/json
    {
  "url": "https://new-endpoint.com/webhook"
}

    #### Delete Webhook

    DELETE /tally/webhooks/{webhookId}

    #### List Webhook Events

    GET /tally/webhooks/{webhookId}/events

    #### Retry Webhook Event

    POST /tally/webhooks/{webhookId}/events/{eventId}

    Pagination

    Tally uses page-based pagination:

    GET /tally/forms?page=1&limit=50

    Response includes pagination info:

    {
  "items": [...],
  "page": 1,
  "limit": 50,
  "total": 100,
  "hasMore": true
}

    For submissions, cursor-based pagination is also available using afterId.

    Code Examples

    JavaScript

    const response = await fetch(
  'https://api.maton.ai/tally/forms',
  {
    headers: {
      'Authorization': Bearer ${process.env.MATON_API_KEY},
      'User-Agent': 'Maton/1.0'
    }
  }
);
const data = await response.json();
console.log(data.items);

    Python

    import os
import requests
    response = requests.get(
    'https://api.maton.ai/tally/forms',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'User-Agent': 'Maton/1.0'
    }
)
data = response.json()
print(data['items'])

    Create Form and Get Submissions

    import os
import requests
import uuid
    headers = {
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'User-Agent': 'Maton/1.0'
}
    Create a simple form
    
form_data = {
    'status': 'DRAFT',
    'blocks': [
        {
            'type': 'FORM_TITLE',
            'uuid': str(uuid.uuid4()),
            'groupUuid': str(uuid.uuid4()),
            'groupType': 'FORM_TITLE',
            'title': 'Contact Form',
            'payload': {}
        },
        {
            'type': 'INPUT_EMAIL',
            'uuid': str(uuid.uuid4()),
            'groupUuid': str(uuid.uuid4()),
            'groupType': 'INPUT_EMAIL',
            'title': 'Your email',
            'payload': {}
        }
    ]
}
    response = requests.post(
    'https://api.maton.ai/tally/forms',
    headers=headers,
    json=form_data
)
form = response.json()
print(f"Created form: {form['id']}")
    Get submissions for a form
    
response = requests.get(
    f'https://api.maton.ai/tally/forms/{form["id"]}/submissions',
    headers=headers
)
submissions = response.json()
print(f"Total submissions: {submissions['totalNumberOfSubmissionsPerFilter']['all']}")

    Notes

  • Form and workspace IDs are short alphanumeric strings (e.g., GxdRaQ)
  • Block uuid and groupUuid fields must be valid UUIDs (GUIDs)
  • Creating workspaces requires a Pro subscription
  • The API is in public beta and subject to changes
  • Rate limit: 100 requests per minute
  • Use webhooks instead of polling for real-time submission notifications
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

    • Error Handling

    | Status | Meaning | |--------|---------| | 400 | Missing Tally connection or validation error | | 401 | Invalid or missing Maton API key | | 403 | Insufficient permissions | | 404 | Resource not found | | 429 | Rate limited (100 req/min) | | 4xx/5xx | Passthrough error from Tally API |

    Troubleshooting: API Key Issues

    1. Check that the MATON_API_KEY environment variable is set:

    echo $MATON_API_KEY

    2. Verify the API key is valid by listing connections:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Troubleshooting: Invalid App Name

    1. Ensure your URL path starts with tally. For example:

  • Correct: https://api.maton.ai/tally/forms
  • Incorrect: https://api.maton.ai/forms

    • Resources

  • Tally API Introduction
  • Tally API Reference
  • Tally Help Center
  • Maton Community
  • Maton Support

    • πŸ’‘ Examples

    # List your forms
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/tally/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('User-Agent', 'Maton/1.0')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    πŸ“‹ Tips & Best Practices

  • Form and workspace IDs are short alphanumeric strings (e.g., GxdRaQ)
  • Block uuid and groupUuid fields must be valid UUIDs (GUIDs)
  • Creating workspaces requires a Pro subscription
  • The API is in public beta and subject to changes
  • Rate limit: 100 requests per minute
  • Use webhooks instead of polling for real-time submission notifications
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments