Creating a form with settings

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
}