Tally

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

Reference

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

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.

List Questions

GET /tally/forms/{formId}/questions

Response:

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

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}

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.

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

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}

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

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}

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

GET /tally/webhooks

Note: Listing webhooks may require specific permissions.

Create Webhook

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

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}

Tally

Reference

Get Current User

List Forms

Get Form

Create Form

Update Form

Delete Form

List Questions

List Submissions

Get Submission

Delete Submission

List Workspaces

Get Workspace

Create Workspace

Update Workspace

Delete Workspace

List Users

Remove User

List Invites

Create Invite

Cancel Invite

List Webhooks

Create Webhook

Update Webhook

Delete Webhook

List Webhook Events

Retry Webhook Event

Resources

On this page