​
Prerequisites

  • A Tally account
  • An API key

​
Request

To create a form with a mention, you’ll need to send a POST request with the form blocks, including the mentions as part of the TITLE block.

curl -X POST 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "e206d8e8-70ad-45c4-b731-775049b43e73",
      "type": "FORM_TITLE",
      "groupUuid": "8c6a61d5-0489-46ec-9498-930907ffb306",
      "groupType": "TEXT",
      "payload": {
        "html": "Hello <span class=\"mention\" data-uuid=\"0f7b3637-61b6-4faa-a93a-a6a31ff5ac63\">@name</span>",
        "mentions": [
          {
            "uuid": "0f7b3637-61b6-4faa-a93a-a6a31ff5ac63",
            "field": {
              "uuid": "16826368-6cce-4066-b1da-be466f851c2d",
              "type": "HIDDEN_FIELD",
              "questionType": "HIDDEN_FIELDS",
              "blockGroupUuid": "203e6532-22a0-4421-b720-5d88d603e618",
              "title": "name"
            },
            "defaultValue": "there"
          }
        ]
      }
    },
    {
      "uuid": "98eada2b-9a1e-430a-b20e-ff94ab01b5ea",
      "type": "HIDDEN_FIELDS",
      "groupUuid": "203e6532-22a0-4421-b720-5d88d603e618",
      "groupType": "HIDDEN_FIELDS",
      "payload": {
        "hiddenFields": [
          {
            "uuid": "16826368-6cce-4066-b1da-be466f851c2d",
            "name": "name"
          }
        ]
      }
    }
  ]
}'

​
Response

The API will respond with a 200 status code and return the newly created form:

{
  "numberOfSubmissions": 0,
  "id": "w4AGDr",
  "name": "Hello @name",
  "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 a mention of the name hidden field.


Which can be auto populated using the name query parameter.