Creating forms

Create a new form

curl --request POST \
  --url https://api.tally.so/forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "BLANK",
  "blocks": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "FORM_TITLE",
      "groupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "groupType": "FORM_TITLE",
      "payload": {
        "html": "<string>",
        "logo": "<string>",
        "cover": "<string>",
        "coverSettings": {
          "objectPositionYPercent": 123
        },
        "mentions": [
          {
            "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "field": {
              "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "InputField",
              "questionType": "FORM_TITLE",
              "blockGroupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "title": "<string>",
              "calculatedFieldType": "NUMBER"
            },
            "defaultValue": {}
          }
        ],
        "button": {
          "label": "<string>"
        }
      }
    }
  ],
  "workspaceId": "<string>",
  "templateId": "<string>",
  "settings": {
    "language": "<string>",
    "isClosed": false,
    "closeMessageTitle": "<string>",
    "closeMessageDescription": "<string>",
    "closeTimezone": "<string>",
    "closeDate": "<string>",
    "closeTime": "<string>",
    "submissionsLimit": 1,
    "uniqueSubmissionKey": "<string>",
    "redirectOnCompletion": "<string>",
    "hasSelfEmailNotifications": false,
    "selfEmailTo": "<string>",
    "selfEmailReplyTo": "<string>",
    "selfEmailSubject": "<string>",
    "selfEmailFromName": "<string>",
    "selfEmailBody": "<string>",
    "hasRespondentEmailNotifications": false,
    "respondentEmailTo": "<string>",
    "respondentEmailReplyTo": "<string>",
    "respondentEmailSubject": "<string>",
    "respondentEmailFromName": "<string>",
    "respondentEmailBody": "<string>",
    "hasProgressBar": false,
    "hasPartialSubmissions": false,
    "pageAutoJump": false,
    "saveForLater": true,
    "styles": "<string>",
    "password": "<string>",
    "submissionsDataRetentionDuration": 1,
    "submissionsDataRetentionUnit": "<string>"
  }
}
'

{
  "id": "<string>",
  "name": "<string>",
  "workspaceId": "<string>",
  "status": "BLANK",
  "numberOfSubmissions": 123,
  "isClosed": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "payments": [
    {
      "amount": 123,
      "currency": "<string>"
    }
  ]
}

POST

forms

Create a new form

curl --request POST \
  --url https://api.tally.so/forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "BLANK",
  "blocks": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "FORM_TITLE",
      "groupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "groupType": "FORM_TITLE",
      "payload": {
        "html": "<string>",
        "logo": "<string>",
        "cover": "<string>",
        "coverSettings": {
          "objectPositionYPercent": 123
        },
        "mentions": [
          {
            "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "field": {
              "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "InputField",
              "questionType": "FORM_TITLE",
              "blockGroupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "title": "<string>",
              "calculatedFieldType": "NUMBER"
            },
            "defaultValue": {}
          }
        ],
        "button": {
          "label": "<string>"
        }
      }
    }
  ],
  "workspaceId": "<string>",
  "templateId": "<string>",
  "settings": {
    "language": "<string>",
    "isClosed": false,
    "closeMessageTitle": "<string>",
    "closeMessageDescription": "<string>",
    "closeTimezone": "<string>",
    "closeDate": "<string>",
    "closeTime": "<string>",
    "submissionsLimit": 1,
    "uniqueSubmissionKey": "<string>",
    "redirectOnCompletion": "<string>",
    "hasSelfEmailNotifications": false,
    "selfEmailTo": "<string>",
    "selfEmailReplyTo": "<string>",
    "selfEmailSubject": "<string>",
    "selfEmailFromName": "<string>",
    "selfEmailBody": "<string>",
    "hasRespondentEmailNotifications": false,
    "respondentEmailTo": "<string>",
    "respondentEmailReplyTo": "<string>",
    "respondentEmailSubject": "<string>",
    "respondentEmailFromName": "<string>",
    "respondentEmailBody": "<string>",
    "hasProgressBar": false,
    "hasPartialSubmissions": false,
    "pageAutoJump": false,
    "saveForLater": true,
    "styles": "<string>",
    "password": "<string>",
    "submissionsDataRetentionDuration": 1,
    "submissionsDataRetentionUnit": "<string>"
  }
}
'

{
  "id": "<string>",
  "name": "<string>",
  "workspaceId": "<string>",
  "status": "BLANK",
  "numberOfSubmissions": 123,
  "isClosed": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "payments": [
    {
      "amount": 123,
      "currency": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

status

enum<string>

required

Initial status of the form

Available options:

BLANK,

DRAFT,

PUBLISHED,

DELETED

blocks

object[]

required

Show child attributes

blocks.uuid

string<uuid>

required

blocks.type

enum<string>

required

Available options:

FORM_TITLE,

TEXT,

LABEL,

TITLE,

HEADING_1,

HEADING_2,

HEADING_3,

DIVIDER,

PAGE_BREAK,

THANK_YOU_PAGE,

IMAGE,

EMBED,

EMBED_VIDEO,

EMBED_AUDIO,

QUESTION,

MATRIX,

INPUT_TEXT,

INPUT_NUMBER,

INPUT_EMAIL,

INPUT_LINK,

INPUT_PHONE_NUMBER,

INPUT_DATE,

INPUT_TIME,

TEXTAREA,

FILE_UPLOAD,

LINEAR_SCALE,

RATING,

HIDDEN_FIELDS,

MULTIPLE_CHOICE_OPTION,

CHECKBOX,

DROPDOWN_OPTION,

RANKING_OPTION,

MULTI_SELECT_OPTION,

PAYMENT,

SIGNATURE,

MATRIX_ROW,

MATRIX_COLUMN,

WALLET_CONNECT,

CONDITIONAL_LOGIC,

CALCULATED_FIELDS,

CAPTCHA,

RESPONDENT_COUNTRY

blocks.groupUuid

string<uuid>

required

blocks.groupType

enum<string>

required

Available options:

FORM_TITLE,

TEXT,

LABEL,

TITLE,

HEADING_1,

HEADING_2,

HEADING_3,

DIVIDER,

PAGE_BREAK,

THANK_YOU_PAGE,

IMAGE,

EMBED,

EMBED_VIDEO,

EMBED_AUDIO,

QUESTION,

MATRIX,

INPUT_TEXT,

INPUT_NUMBER,

INPUT_EMAIL,

INPUT_LINK,

INPUT_PHONE_NUMBER,

INPUT_DATE,

INPUT_TIME,

TEXTAREA,

FILE_UPLOAD,

LINEAR_SCALE,

RATING,

HIDDEN_FIELDS,

MULTIPLE_CHOICE_OPTION,

CHECKBOX,

DROPDOWN_OPTION,

RANKING_OPTION,

MULTI_SELECT_OPTION,

PAYMENT,

SIGNATURE,

MATRIX_ROW,

MATRIX_COLUMN,

WALLET_CONNECT,

CONDITIONAL_LOGIC,

CALCULATED_FIELDS,

CAPTCHA,

RESPONDENT_COUNTRY

blocks.payload

FormTitlePayload · object

Show child attributes

blocks.payload.html

string

blocks.payload.logo

string<uri>

blocks.payload.cover

string<uri>

blocks.payload.coverSettings

object

Show child attributes

blocks.payload.coverSettings.objectPositionYPercent

number

blocks.payload.mentions

object[]

Show child attributes

blocks.payload.mentions.uuid

string<uuid>

required

blocks.payload.mentions.field

object

required

Show child attributes

blocks.payload.mentions.field.uuid

string<uuid>

required

blocks.payload.mentions.field.type

enum<string>

required

Available options:

InputField,

CalculatedField,

HiddenField

blocks.payload.mentions.field.questionType

enum<string>

required

Available options:

FORM_TITLE,

TEXT,

LABEL,

TITLE,

HEADING_1,

HEADING_2,

HEADING_3,

DIVIDER,

PAGE_BREAK,

THANK_YOU_PAGE,

IMAGE,

EMBED,

EMBED_VIDEO,

EMBED_AUDIO,

QUESTION,

MATRIX,

INPUT_TEXT,

INPUT_NUMBER,

INPUT_EMAIL,

INPUT_LINK,

INPUT_PHONE_NUMBER,

INPUT_DATE,

INPUT_TIME,

TEXTAREA,

FILE_UPLOAD,

LINEAR_SCALE,

RATING,

HIDDEN_FIELDS,

MULTIPLE_CHOICE_OPTION,

CHECKBOX,

DROPDOWN_OPTION,

RANKING_OPTION,

MULTI_SELECT_OPTION,

PAYMENT,

SIGNATURE,

MATRIX_ROW,

MATRIX_COLUMN,

WALLET_CONNECT,

CONDITIONAL_LOGIC,

CALCULATED_FIELDS,

CAPTCHA,

RESPONDENT_COUNTRY

blocks.payload.mentions.field.blockGroupUuid

string<uuid>

required

blocks.payload.mentions.field.title

string

blocks.payload.mentions.field.calculatedFieldType

enum<string>

Available options:

NUMBER,

TEXT

blocks.payload.mentions.defaultValue

object

Any value

blocks.payload.button

object

Show child attributes

blocks.payload.button.label

string

workspaceId

string

ID of the workspace to create the form in. If not provided, uses the user's default workspace

templateId

string

ID of the template to base the form on

settings

object

Show child attributes

settings.language

string | null

Maximum string length: 12

settings.isClosed

boolean

default:false

settings.closeMessageTitle

string | null

settings.closeMessageDescription

string | null

settings.closeTimezone

string | null

Maximum string length: 256

settings.closeDate

string | null

Maximum string length: 12

settings.closeTime

string | null

Maximum string length: 12

settings.submissionsLimit

integer<int64> | null

Required range: x >= 0

settings.uniqueSubmissionKey

string | null

settings.redirectOnCompletion

string | null

settings.hasSelfEmailNotifications

boolean

default:false

settings.selfEmailTo

string | null

settings.selfEmailReplyTo

string | null

settings.selfEmailSubject

string | null

settings.selfEmailFromName

string | null

settings.selfEmailBody

string | null

settings.hasRespondentEmailNotifications

boolean

default:false

settings.respondentEmailTo

string | null

settings.respondentEmailReplyTo

string | null

settings.respondentEmailSubject

string | null

settings.respondentEmailFromName

string | null

settings.respondentEmailBody

string | null

settings.hasProgressBar

boolean

default:false

settings.hasPartialSubmissions

boolean

default:false

settings.pageAutoJump

boolean

default:false

settings.saveForLater

boolean

default:true

settings.styles

string | null

settings.password

string | null

settings.submissionsDataRetentionDuration

integer<int64> | null

Required range: x >= 0

settings.submissionsDataRetentionUnit

string | null

Maximum string length: 12

Response

Form created successfully

string

required

name

string

required

workspaceId

string

required

status

enum<string>

required

Available options:

BLANK,

DRAFT,

PUBLISHED,

DELETED

numberOfSubmissions

number

required

isClosed

boolean

required

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

payments

object[]

Show child attributes

payments.amount

number

payments.currency

string

Listing forms Fetching forms

⌘I

Getting started

Users

Organizations

Forms

Workspaces

Webhooks

Authorizations

Body

Response