Forms

The Forms resource covers listing, fetching, creating, updating, and deleting forms, plus question and submission access.

Initialization

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

List Forms

Method

client.forms.all(
    page: int = 1,
    limit: int = 50,
    workspace_ids: list[str] | None = None,
) -> PaginatedForms

Example

forms = client.forms.all(page=1, limit=10)

print(forms.page, forms.total, forms.has_more)
for form in forms.items:
    print(form.id, form.name, form.status.value)

Notes

• workspace_ids accepts a list of workspace IDs
• The returned collection is items, not data
• PaginatedForms exposes page, limit, total, and has_more

Official Reference

List Forms

---

Get Form

Method

client.forms.get(form_id: str) -> FormDetails

Example

form = client.forms.get("wXYz123")

print(form.name)
print(form.number_of_submissions)
print(form.settings.has_progress_bar)
print(len(form.blocks))

Official Reference

Get Form

---

Create Form

Method

client.forms.create(
    status: FormStatus | str,
    blocks: list[FormBlock] | list[dict],
    workspace_id: str | None = None,
    template_id: str | None = None,
    settings: FormSettings | dict | None = None,
) -> FormCreated

Example

from tally.models import BlockType, FormBlock, FormSettings, FormStatus

form = client.forms.create(
    status=FormStatus.DRAFT,
    workspace_id="ws_123",
    blocks=[
        FormBlock(
            uuid="block-1",
            type=BlockType.FORM_TITLE,
            group_uuid="block-1",
            group_type=BlockType.FORM_TITLE,
            payload={"html": "<h1>Customer Feedback</h1>"},
        )
    ],
    settings=FormSettings(
        has_progress_bar=True,
        save_for_later=True,
    ),
)

Official Reference

Create Form

---

Update Form

Method

client.forms.update(
    form_id: str,
    name: str | None = None,
    status: FormStatus | str | None = None,
    blocks: list[FormBlock] | list[dict] | None = None,
    settings: FormSettings | dict | None = None,
) -> Form

Example

form = client.forms.update(
    "wXYz123",
    name="Customer Feedback 2026",
    status="PUBLISHED",
    settings={"hasProgressBar": True},
)

print(form.id, form.status.value)

Official Reference

Update Form

---

Delete Form

Method

client.forms.delete(form_id: str) -> None

Official Reference

Delete Form

---

List Questions

Method

client.forms.list_questions(form_id: str) -> QuestionsList

Example

result = client.forms.list_questions("wXYz123")

print(result.has_responses)
for question in result.questions:
    print(question.id, question.title, question.type)
    for field in question.fields:
        print(field.uuid, field.title, field.type)

Notes

• QuestionsList exposes questions and has_responses
• QuestionField exposes uuid, type, question_type, block_group_uuid, and title

Official Reference

List Questions

---

List Submissions

Method

client.forms.list_submissions(
    form_id: str,
    page: int = 1,
    filter: SubmissionFilter | str | None = None,
    start_date: str | None = None,
    end_date: str | None = None,
    after_id: str | None = None,
) -> PaginatedSubmissions

Example

from tally.models import SubmissionFilter

result = client.forms.list_submissions(
    "wXYz123",
    page=1,
    filter=SubmissionFilter.ALL,
)

print(result.total_number_of_submissions_per_filter.all)
for submission in result.submissions:
    print(submission.id, submission.submitted_at, submission.is_completed)

Notes

• Date filters use start_date and end_date
• Cursor-style pagination can use after_id
• The returned collections are questions and submissions

Official Reference

List Submissions

---

Get Submission

Method

client.forms.get_submission(
    form_id: str,
    submission_id: str,
) -> SubmissionWithQuestions

Example

result = client.forms.get_submission("wXYz123", "sub_abc456")

print(result.submission.id)
for response in result.submission.responses:
    print(response.question_id, response.value)

Official Reference

Get Submission

---

Delete Submission

Method

client.forms.delete_submission(
    form_id: str,
    submission_id: str,
) -> None

Official Reference

Delete Submission

---

Models

Form

Form dataclass

Represents a Tally form.

FormCreated

FormCreated dataclass

Response from creating a form.

FormDetails

FormDetails dataclass

Represents a complete Tally form with all blocks and settings.

This is returned by the get() method and includes the full form structure, unlike the simplified Form model used in list operations.

PaginatedForms

PaginatedForms dataclass

Represents a paginated response of forms.

Question

Question dataclass

Represents a question in a Tally form.

QuestionsList

QuestionsList dataclass

Represents the questions payload returned for a form.

Submission

Submission dataclass

Represents a form submission.

SubmissionWithQuestions

SubmissionWithQuestions dataclass

Represents a submission response with its associated questions.

This is the response structure from the get_submission() endpoint, which includes both the submission details and all form questions.

PaginatedSubmissions

PaginatedSubmissions dataclass

Represents a paginated response of form submissions.