Listing submissions

List form submissions

curl --request GET \
  --url https://api.tally.so/forms/{formId}/submissions \
  --header 'Authorization: Bearer <token>'

{
  "page": 123,
  "limit": 123,
  "hasMore": true,
  "totalNumberOfSubmissionsPerFilter": {
    "all": 123,
    "completed": 123,
    "partial": 123
  },
  "questions": [
    {
      "id": "<string>",
      "type": "FORM_TITLE",
      "title": "<string>",
      "isTitleModifiedByUser": true,
      "formId": "<string>",
      "isDeleted": true,
      "numberOfResponses": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "fields": [
        {
          "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "FORM_TITLE",
          "blockGroupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "title": "<string>"
        }
      ]
    }
  ],
  "submissions": [
    {
      "id": "<string>",
      "formId": "<string>",
      "isCompleted": true,
      "submittedAt": "2023-11-07T05:31:56Z",
      "responses": [
        {
          "questionId": "<string>",
          "value": "<string>"
        }
      ]
    }
  ]
}

GET

forms

{formId}

submissions

List form submissions

curl --request GET \
  --url https://api.tally.so/forms/{formId}/submissions \
  --header 'Authorization: Bearer <token>'

{
  "page": 123,
  "limit": 123,
  "hasMore": true,
  "totalNumberOfSubmissionsPerFilter": {
    "all": 123,
    "completed": 123,
    "partial": 123
  },
  "questions": [
    {
      "id": "<string>",
      "type": "FORM_TITLE",
      "title": "<string>",
      "isTitleModifiedByUser": true,
      "formId": "<string>",
      "isDeleted": true,
      "numberOfResponses": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "fields": [
        {
          "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "FORM_TITLE",
          "blockGroupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "title": "<string>"
        }
      ]
    }
  ],
  "submissions": [
    {
      "id": "<string>",
      "formId": "<string>",
      "isCompleted": true,
      "submittedAt": "2023-11-07T05:31:56Z",
      "responses": [
        {
          "questionId": "<string>",
          "value": "<string>"
        }
      ]
    }
  ]
}

Looking for real-time submissions? The most efficient way to instantly retrieve new submissions is by using a webhook. This allows you to receive data as soon as a form is submitted, without needing to poll the API.

Authorizations

Authorization

string

header

required

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

Path Parameters

formId

string

required

The ID of the form

Query Parameters

page

number

Page number for pagination (default: 1)

filter

enum<string>

Filter submissions by status

Available options:

all,

completed,

partial

startDate

string<date-time>

Filter submissions submitted on or after this date (ISO 8601 format)

endDate

string<date-time>

Filter submissions submitted on or before this date (ISO 8601 format)

afterId

string

Get submissions that came after a specific submission ID

Response

List of form submissions

page

number

Current page number

limit

number

Number of submissions per page

hasMore

boolean

Whether there are more pages available

totalNumberOfSubmissionsPerFilter

object

Show child attributes

totalNumberOfSubmissionsPerFilter.all

number

Total number of all submissions

totalNumberOfSubmissionsPerFilter.completed

number

Total number of completed submissions

totalNumberOfSubmissionsPerFilter.partial

number

Total number of partial submissions

questions

object[]

List of form questions

Show child attributes

questions.id

string

questions.type

enum<string>

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

questions.title

string

questions.isTitleModifiedByUser

boolean

questions.formId

string

questions.isDeleted

boolean

questions.numberOfResponses

integer

questions.createdAt

string<date-time>

questions.updatedAt

string<date-time>

questions.fields

object[]

Show child attributes

questions.fields.uuid

string<uuid>

questions.fields.type

enum<string>

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

questions.fields.blockGroupUuid

string<uuid>

questions.fields.title

string

submissions

object[]

List of form submissions

Show child attributes

submissions.id

string

Submission ID

submissions.formId

string

Form ID

submissions.isCompleted

boolean

Whether the submission is completed

submissions.submittedAt

string<date-time>

When the submission was submitted

submissions.responses

object[]

List of responses to form questions

Show child attributes

submissions.responses.questionId

string

Question ID

submissions.responses.value

Response value

Listing questions Fetching submissions

⌘I

Getting started

Users

Organizations

Forms

Workspaces

Webhooks

Authorizations

Path Parameters

Query Parameters

Response