Tally

Tally’s forms API at tally-version: 2026-08-04. The two jobs an agent is pointed at Tally for are reading the responses that came in and spinning up a form, and both are easy to get subtly wrong: a form is a flat list of blocks joined by groupUuid rather than a list of questions, and polling submissions runs into a 100-requests-a-minute limit quickly. Tally publishes no client library, so the conformance suite pins the OpenAPI document Tally serves and validates every response the twin gives against it. Slug: tally

What it models

Area	Modelled
Starting account	One organization on the Pro plan, its owner, and the workspace Tally gives a new account, `My workspace`
Authentication	A `tly-…` key in `Authorization: Bearer`, matched exactly; Tally’s `401 text/plain Unauthorized` for a key it cannot read and for a path it has no route for, and its JSON `UNAUTHORIZED_ACTION` for a key it does not know; the `tally-version` header; `GET /users/me`
Workspaces and folders	List, create, retrieve, rename and delete workspaces with their members and invites; nested folders, renamed and deleted with their subtree; deleting either trashes the forms inside
Forms and blocks	List with `workspaceIds` and page numbers, newest edit first; create, retrieve, update and trash; every block type Tally accepts, validated the way Tally validates them; settings with Tally’s defaults; draft blocks on a published form; close dates and submission limits closing a form
Questions	Derived from a form’s published blocks — one per answerable group, titled from the `TITLE` block before it or the input’s placeholder — keeping their identifiers across a republish
Submissions	Listed with `filter`, `startDate`, `endDate`, `afterId`, `page` and `limit`, with Tally’s per-filter totals; retrieved and deleted; answers typed by their question, choices as option texts
Webhooks	Create, list, update and delete, and the event log a completed submission appends to
Organization	Its users, invites by email into workspaces, and cancelling them
Errors and limits	Tally’s Joi validation messages, checked in Tally’s order and before the key is looked up; its not-found and business-rule envelopes; 100 requests a minute with the `x-ratelimit-*` headers and the `429`

Advancing closes forms whose close date has passed, completes partial submissions that were marked to complete, and appends a FORM_RESPONSE event to each enabled webhook for every newly completed submission.

Not modelled

Analytics (metrics, visits, submissions over time, dimensions and drop-off), webhook delivery, form templates, file uploads, payments, hidden and calculated fields as questions, the preview and PDF pages a submission links to, and every response shape older than 2026-08-04. An endpoint Tally has and the twin has not built answers an explicit 501 in Tally’s envelope; a path Tally does not have gets Tally’s own 401 text/plain Unauthorized.

Getting Started

Concepts

Interfaces

Request a twin

What it models

Not modelled

​What it models

​Not modelled

What it models

Not modelled