Build a Form with Tally.so API in JSON

Creating custom forms with the Tally.so API is simple and flexible. Here's a quick example of how to build a basic "Interest Form" using JSON:

{
  "title": "Interest Form",
  "description": "Let us know if you're interested in collaborating!",
  "status": "published",
  "submitButtonText": "Submit",
  "fields": [
    {
      "groupUuid": "group-1",
      "label": "Name",
      "type": "text",
      "placeholder": "Your full name",
      "required": true
    },
    {
      "groupUuid": "group-1",
      "label": "Email",
      "type": "email",
      "placeholder": "you@example.com",
      "required": true
    },
    {
      "groupUuid": "group-2",
      "label": "Interested in...",
      "type": "choice",
      "required": true,
      "options": [
        { "label": "Startups", "value": "startups" },
        { "label": "AI", "value": "ai" },
        { "label": "Web3", "value": "web3" }
      ]
    }
  ]
}

Just POST this JSON to https://api.tally.so/forms and your form is live! Great for gathering leads, feedback, or collab requests—all via API.

Pro tip: group fields using groupUuid to control layout or sections.

Here are all the main keys you can use when creating a form with POST https://api.tally.so/forms:

---

🧱 Top‑level Parameters

• workspaceId <string> — (optional) assign form to a workspace.

• templateId <string> — create from an existing template.

• status "BLANK" | "DRAFT" | "PUBLISHED" — form state (developers.tally.so).

• blocks <array> — define form content and structure — see Blocks section below .

• settings <object> — form behavior & theming — see Settings section below (developers.tally.so).

---

🧩 Blocks (Form Elements)

Each block must include:

• uuid <string> — unique per block.

• type <enum> — e.g. FORM_TITLE, TITLE, INPUT_TEXT, INPUT_EMAIL, TEXTAREA, etc. (developers.tally.so)

• groupUuid <string> — groups title + input pairs visually.

• groupType <enum> — e.g. TEXT, QUESTION, INPUT_EMAIL, etc.

• payload <object>:

  • For titles: html or title

  • For input fields: isRequired, placeholder

  • Input types include: INPUT_TEXT, INPUT_EMAIL, INPUT_LINK, TEXTAREA, etc. (developers.tally.so)

---

⚙️ Settings (Options & Behavior)

Inside the settings object you can specify:

• language <string> — e.g. "fr"

• isClosed <boolean>

• closeMessageTitle, closeMessageDescription

• closeTimezone, closeDate, closeTime

• submissionsLimit <integer>

• uniqueSubmissionKey <string> or mention object (to prevent duplicate entries)

• redirectOnCompletion <string> or mention object

• hasSelfEmailNotifications <boolean>

• selfEmailTo, selfEmailReplyTo, selfEmailSubject, selfEmailFromName, selfEmailBody

• hasRespondentEmailNotifications and related respondentEmail* fields

• hasProgressBar, hasPartialSubmissions, pageAutoJump, saveForLater

• styles <string> or <object> (for CSS/themes)

• password <string> (if you want a pass‑protected form)

• submissionsDataRetentionDuration, submissionsDataRetentionUnit (developers.tally.so)

---

📌 Mentions and Dynamic Features

• You can embed mentions using HTML + mentions arrays inside payload, selfEmailBody, redirectOnCompletion, etc. (developers.tally.so)

---

🎯 Example

{
  "workspaceId": "abc123",
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "…",
      "type": "FORM_TITLE",
      "groupUuid": "…",
      "groupType": "TEXT",
      "payload": {
        "html": "My Cool Form",
        "button": { "label": "Send it!" }
      }
    },
    {
      "uuid": "…",
      "type": "INPUT_TEXT",
      "groupUuid": "…",
      "groupType": "QUESTION",
      "payload": {
        "isRequired": true,
        "placeholder": "Your name here"
      }
    }
  ],
  "settings": {
    "language": "en",
    "redirectOnCompletion": "https://example.com/thanks",
    "hasSelfEmailNotifications": true,
    "selfEmailTo": "me@site.com",
    "styles": {
      "theme": "CUSTOM",
      "color": {
        "accent": "#007aff",
        "buttonText": "#fff"
      },
      "css": ".tally-submit-button { border-radius: 8px; }"
    }
  }
}

---

📚 Where to Learn More

• Full POST /forms reference: block types, settings, payload specifics (developers.tally.so)

• Advanced examples (language, CSS, close dates, email, redirect, etc.) (developers.tally.so)

---