Prerequisites

  • A Tally account
  • An API key

Request

To create a form with settings, you’ll need to send a POST request with the form blocks, including the settings. In this example we’ll configure the following settings;
  • French language
  • A closing date & time of of 2026-01-09, 09:41 (Paris time)
  • A submissions limit of 42
  • A unique submission key of the Email field
  • A redirect on completion of the URL field
  • A self email notification to me@company.com
  • A self email reply to hello@company.com
  • A custom theme with some specific colors & CSS
curl -X POST 'https://api.tally.so/forms' \
-H 'Authorization: Bearer tly-31Aio2vZNKwxGSmaDgutZHLaCg3s7R6c' \
-H 'Content-Type: application/json' \
-d '{
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "ea43ce44-71ae-4e79-b6c2-40e739f61c4b",
      "type": "FORM_TITLE",
      "groupUuid": "36cfc6e4-6c15-495b-a415-be648f3214b6",
      "groupType": "TEXT",
      "payload": {
        "html": "Hello world"
      }
    },
    {
      "uuid": "1ff064ca-d869-48f2-89eb-bba61101385b",
      "type": "TITLE",
      "groupUuid": "aa1fe42e-4ba9-4e15-a63f-fb5f7dd5d5d7",
      "groupType": "QUESTION",
      "payload": {
        "html": "Email"
      }
    },
    {
      "uuid": "3f437d91-9501-4a73-b793-0abd9585d55a",
      "type": "INPUT_EMAIL",
      "groupUuid": "6f34fcbe-4d2e-49ca-94c5-395809e7e9e6",
      "groupType": "INPUT_EMAIL",
      "payload": {
        "isRequired": true,
        "placeholder": ""
      }
    },
    {
      "uuid": "04e62978-23f7-4121-8f9b-6c37359e60aa",
      "type": "TITLE",
      "groupUuid": "4cf183be-7eea-4a7b-ab1e-3caa77995d0d",
      "groupType": "QUESTION",
      "payload": {
        "html": "URL"
      }
    },
    {
      "uuid": "6033c312-df41-4cae-9ee4-b3893d0a8f5a",
      "type": "INPUT_LINK",
      "groupUuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
      "groupType": "INPUT_LINK",
      "payload": {
        "isRequired": true,
        "placeholder": ""
      }
    }
  ],
  "settings": {
    "language": "fr",
    "closeTimezone": "Europe/Paris",
    "closeDate": "2026-01-09",
    "closeTime": "09:41",
    "submissionsLimit": 42,
    "uniqueSubmissionKey": {
      "html": "<span class=\"mention\" data-uuid=\"36d6ef12-d5b0-4491-b675-5c01cb4799a0\">@Email</span>",
      "mentions": [
        {
          "uuid": "36d6ef12-d5b0-4491-b675-5c01cb4799a0",
          "field": {
            "uuid": "6f34fcbe-4d2e-49ca-94c5-395809e7e9e6",
            "type": "INPUT_FIELD",
            "questionType": "INPUT_EMAIL",
            "blockGroupUuid": "6f34fcbe-4d2e-49ca-94c5-395809e7e9e6",
            "title": "Email"
          }
        }
      ]
    },
    "redirectOnCompletion": {
      "html": "<span class=\"mention\" data-uuid=\"42283ab9-9efe-4b58-bac5-b4fbc04ab945\">@URL</span>",
      "mentions": [
        {
          "uuid": "42283ab9-9efe-4b58-bac5-b4fbc04ab945",
          "field": {
            "uuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "type": "INPUT_FIELD",
            "questionType": "INPUT_LINK",
            "blockGroupUuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "title": "URL"
          }
        }
      ]
    },
    "hasSelfEmailNotifications": true,
    "selfEmailTo": {
      "html": "me@company.com",
      "mentions": []
    },
    "selfEmailReplyTo": {
      "html": "hello@company.com",
      "mentions": []
    },
    "selfEmailSubject": null,
    "selfEmailFromName": null,
    "selfEmailBody": {
      "html": "<b>URL:</a> <span class=\"mention\" data-uuid=\"d036b126-f593-417d-b9a7-0a50db496625\">@URL</span>",
      "mentions": [
        {
          "uuid": "d036b126-f593-417d-b9a7-0a50db496625",
          "field": {
            "uuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "type": "INPUT_FIELD",
            "questionType": "INPUT_LINK",
            "blockGroupUuid": "be4ecfde-635e-4a48-bee5-e142907f4c25",
            "title": "URL"
          }
        }
      ]
    },
    "styles": {
      "theme": "CUSTOM",
      "color": {
        "background": "#ffffff",
        "text": "#37352f",
        "accent": "#007aff",
        "buttonBackground": "#007aff",
        "buttonText": "#ffffff"
      },
      "css": ".tally-submit-button svg {\n  display: none;\n}",
      "direction": "ltr"
    }
  }
}'

Response

The API will respond with a 200 status code and return the newly created form:
{
  "numberOfSubmissions": 0,
  "id": "w4AGDr",
  "name": "Hello world",
  "workspaceId": "qnGe3Z",
  "organizationId": "kwob3J",
  "status": "PUBLISHED",
  "updatedAt": "2025-01-14T14:01:47.222Z",
  "createdAt": "2025-01-14T14:01:47.222Z",
  "isClosed": false
}
Your form will now be created with the settings you provided.
Form with dropdown (builder view)

Form with dropdown (builder view)

Form with dropdown (builder view)

Form with dropdown (builder view)