We try to version the API using dates to maintain a highly backwards compatible API. You can
specify a version using the
tally-version header, e.g. tally-version: 2025-02-01.Breaking changes
POST /forms,PATCH /forms/{formId}andPATCH /forms/{formId}/blocksreject aUTILITYfield reference with a400error when itspayloadis not a valid duration, such as{ "days": "1" }. Previously anypayloadwas accepted, which could break the date on the form. Leavingpayloadout still means today.
Breaking changes
PATCH /forms/{formId}withstatus: PUBLISHEDand noblocksis rejected with a400error when the form is not published yet and has no blocks. Previously the form went live with no blocks.
Changed endpoints
PATCH /forms/{formId}
status: PUBLISHEDwithoutblockspublishes the form’s saved draft blocks. Previously the drafts stayed hidden and the form went live with its old blocks, or none.
Breaking changes
- An API key now only works while its creator is a member of the organization the key was created in. When that user leaves or is removed, requests with the key are rejected with a
401error. Previously the key kept working in the user’s new organization. Create a new API key in the new organization instead.
New endpoints
GET /workspaces/{workspaceId}/folders
List a workspace’s foldersPOST /workspaces/{workspaceId}/folders
Create a folderPATCH /workspaces/{workspaceId}/folders/{id}
Rename a folderDELETE /workspaces/{workspaceId}/folders/{id}
Delete a folder and its subfolders, moving any forms they contain to trash
Changed endpoints
GET /workspaces
Each workspace now includes afoldersarrayGET /workspaces/{workspaceId}
The response now includes afoldersarray
New endpoints
GET /forms/{formId}/analytics/metrics
Get aggregate form metricsGET /forms/{formId}/analytics/visits
Get form visits over timeGET /forms/{formId}/analytics/submissions
Get completed and partial submissions over timeGET /forms/{formId}/analytics/dimensions
Get visitor breakdowns by source, browser, OS, device and locationGET /forms/{formId}/analytics/drop-off
Get per-question drop-off statistics
Changed endpoints
POST /forms
Form settings accept rich text (htmlwithmentions) for email and redirect fieldsGET /forms/{formId}
Form settings now return rich text (htmlwithmentions) for email and redirect fieldsPATCH /forms/{formId}
Form settings accept rich text (htmlwithmentions) for email and redirect fields
New endpoints
GET /forms/{formId}/questions
Get form questionsGET /forms/{formId}/submissions/{submissionId}
Get a specific form submissionGET /organizations/{organizationId}/users
View organization usersDELETE /organizations/{organizationId}/users/{userId}
Remove users from organizationGET /organizations/{organizationId}/invites
View pending invitesPOST /organizations/{organizationId}/invites
Invite users to organizationDELETE /organizations/{organizationId}/invites/{inviteId}
Cancel pending invitesGET /webhooks
List configured webhooksGET /webhooks/{webhookId}/events
List webhook eventsPOST /webhooks/{webhookId}/events/{eventId}
Retry webhook events
Changed endpoints
GET /forms/{formId}/submissions
Added new filtering options:startDate,endDate&afterId