Tally

Tally API integration with managed OAuth. Manage forms, submissions, workspaces, webhooks, organization users, and organization invites. All write operations require explicit user approval. Organization user removal and invite management affect account membership. Webhooks send form submission data (which may contain personal information) to external URLs — confirm the destination before creating. Use this skill when users want to manage Tally forms, submissions, workspaces, or organization membership. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key.

byungkyu@byungkyu

Install

openclaw skills install @byungkyu/tally-api

Tally

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

Quick Start

bash

# 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

text

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:

text

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

Environment Variable: Set your API key as MATON_API_KEY:

bash

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

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

Connection Management

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

List Connections

bash

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

bash

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

bash

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:

json

{
  "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

bash

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:

bash

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, webhooks, organization users, and organization invites 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.
Organization membership operations (removing users, creating/cancelling invites) affect who has access to the Tally organization. Confirm the target user/email and intent before executing.
Webhooks send form submission data to external URLs. Submissions may contain personal or sensitive information entered by respondents. Confirm the destination URL and form with the user before creating.

API Reference

User

Get Current User

bash

GET /tally/users/me

Response:

json

{
  "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

bash

GET /tally/forms

Query Parameters:

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

Response:

json

{
  "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

bash

GET /tally/forms/{formId}

Response:

json

{
  "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

bash

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

bash

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

bash

DELETE /tally/forms/{formId}

Moves the form to trash.

Form Questions

List Questions

bash

GET /tally/forms/{formId}/questions

Response:

json

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

Form Submissions

List Submissions

bash

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:

json

{
  "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

bash

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

Delete Submission

bash

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

Workspaces

List Workspaces

bash

GET /tally/workspaces

Response:

json

{
  "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

bash

GET /tally/workspaces/{workspaceId}

Response:

json

{
  "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

bash

POST /tally/workspaces
Content-Type: application/json

{
  "name": "New Workspace"
}

Note: Creating workspaces requires a Pro subscription.

Update Workspace

bash

PATCH /tally/workspaces/{workspaceId}
Content-Type: application/json

{
  "name": "Updated Workspace Name"
}

Delete Workspace

bash

DELETE /tally/workspaces/{workspaceId}

Moves the workspace and all its forms to trash.

Organization Users

Admin scope. User removal permanently revokes a member's access to the organization. Confirm the user's name, email, and intent with the user before executing DELETE operations.

List Users

bash

GET /tally/organizations/{organizationId}/users

Response:

json

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

Remove User

bash

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

Organization Invites

Admin scope. Creating invites grants new users access to the organization. Cancelling invites revokes pending access. Confirm the email and intent before executing.

List Invites

bash

GET /tally/organizations/{organizationId}/invites

Create Invite

bash

POST /tally/organizations/{organizationId}/invites
Content-Type: application/json

{
  "email": "newuser@example.com",
  "workspaceIds": ["3jW9Q1"]
}

Cancel Invite

bash

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

Webhooks

Data transmission. Webhooks send form submission data to the specified external URL. Submissions may contain personal or sensitive respondent information. Confirm the destination URL, form, and event types with the user before creating or updating.

List Webhooks

bash

GET /tally/webhooks

Note: Listing webhooks may require specific permissions.

Create Webhook

bash

POST /tally/webhooks
Content-Type: application/json

{
  "formId": "GxdRaQ",
  "url": "https://example.com/webhook",
  "eventTypes": ["FORM_RESPONSE"]
}

Webhook Event Types:

FORM_RESPONSE - Triggered when a new form response is submitted

Update Webhook

bash

PATCH /tally/webhooks/{webhookId}
Content-Type: application/json

{
  "url": "https://new-endpoint.com/webhook"
}

Delete Webhook

bash

DELETE /tally/webhooks/{webhookId}

List Webhook Events

bash

GET /tally/webhooks/{webhookId}/events

Retry Webhook Event

bash

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

Pagination

Tally uses page-based pagination:

bash

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

Response includes pagination info:

json

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

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

Code Examples

JavaScript

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

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

python

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

Check that the MATON_API_KEY environment variable is set:

bash

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

bash

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

Ensure your URL path starts with tally. For example:

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

Tally

Install

Tally

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

Security & Permissions

API Reference

User

Get Current User

Forms

List Forms

Get Form

Create Form

Update Form

Delete Form

Form Questions

List Questions

Form Submissions

List Submissions

Get Submission

Delete Submission

Workspaces

List Workspaces

Get Workspace

Create Workspace

Update Workspace

Delete Workspace

Organization Users

List Users

Remove User

Organization Invites

List Invites

Create Invite

Cancel Invite

Webhooks

List Webhooks

Create Webhook

Update Webhook

Delete Webhook

List Webhook Events

Retry Webhook Event

Pagination

Code Examples

JavaScript

Python

Create Form and Get Submissions

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: Invalid App Name

Resources

Related skills