> ## Documentation Index
> Fetch the complete documentation index at: https://developers.formstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /forms/{formId}/submissions

Retrieve a paginated list of submissions for a specific form

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Formstack API v2025.0",
    "version": "0.0.4"
  },
  "servers": [
    {
      "url": "https://www.formstack.com/api/v2025",
      "description": "Production server"
    },
    {
      "url": "https://staging-formstack.com/api/v2025",
      "description": "Staging server"
    },
    {
      "url": "https://dev-formstack.com/api/v2025",
      "description": "Development server"
    }
  ],
  "paths": {
    "/forms/{formId}/submissions": {
      "get": {
        "tags": [
          "Submissions",
          "Classic"
        ],
        "description": "Retrieve a paginated list of submissions for a specific form",
        "operationId": "getFormSubmissionsList",
        "parameters": [
          {
            "name": "formId",
            "in": "path",
            "description": "The unique identifier of the form to retrieve submissions from",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "pageNumber",
            "in": "query",
            "description": "Page number for pagination (starting from 1)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/pageNumber"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Maximum number of submissions to return per page (default: 25, max: 100)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/pageSize"
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort order for results (ASC for ascending, DESC for descending)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/order"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "Search term to filter submissions by content across all fields",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/keyword"
            }
          },
          {
            "name": "minTime",
            "in": "query",
            "description": "Return submissions created on or after this date/time (format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in Eastern Time)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/minTime"
            }
          },
          {
            "name": "maxTime",
            "in": "query",
            "description": "Return submissions created on or before this date/time (format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in Eastern Time)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/maxTime"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Search specific fields by ID and value. Use array format in query string: search[0][fieldId]=111&search[0][value]=foo&search[1][fieldId]=112&search[1][value]=bar (supports up to 10 search criteria)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/search"
            },
            "example": "search[0][fieldId]=123456&search[0][value]=john@example.com"
          },
          {
            "name": "data",
            "in": "query",
            "description": "Include field data in the response (true/false)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/data"
            }
          },
          {
            "name": "expandData",
            "in": "query",
            "description": "Include expanded field data with parsed values (true/false)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/expandData"
            }
          },
          {
            "name": "prettyName",
            "in": "query",
            "description": "Include a human-readable name for each submission based on name or email fields (true/false)",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/prettyName"
            }
          },
          {
            "name": "dataFormat",
            "in": "query",
            "description": "Shape of the 'data' field: 'legacy' (default, object keyed by field id) or 'standardized' (array of field objects matching GET /submissions/{id})",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/GetFormSubmissionsListApiDto/properties/dataFormat"
            }
          },
          {
            "name": "X-FS-Encryption-Password",
            "in": "header",
            "description": "Required when form has encryption enabled and data=true or prettyName=true. The encryption password used to decrypt submission data",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormSubmissionsListingApiDto"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Encryption password required or invalid"
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PaginationApiDto": {
        "title": "Pagination Info",
        "description": "Pagination information",
        "properties": {
          "size": {
            "description": "The amount of records returned for this page",
            "type": "integer",
            "nullable": false
          },
          "pageNumber": {
            "description": "The current page number",
            "type": "integer",
            "nullable": false
          },
          "pageSize": {
            "description": "The actual page size",
            "type": "integer",
            "nullable": false
          },
          "totalElements": {
            "description": "The total amount of resources available",
            "type": "integer",
            "nullable": false
          },
          "totalPages": {
            "description": "The total amount of pages available, based on the pageSize",
            "type": "integer",
            "nullable": false
          }
        },
        "type": "object"
      },
      "SearchCriterionDto": {
        "title": "Search Criterion",
        "description": "A single search criterion for filtering by field value",
        "properties": {
          "fieldId": {
            "description": "The ID of the field to search",
            "type": "string",
            "example": "123456"
          },
          "value": {
            "description": "The value to search for in the field",
            "type": "string",
            "example": "john@example.com"
          }
        },
        "type": "object"
      },
      "SubmissionDataAddressValueApiDto": {
        "title": "Submission Data Address Value",
        "description": "Submission data address value response",
        "properties": {
          "address": {
            "description": "First part of the address",
            "type": "string",
            "nullable": true
          },
          "address2": {
            "description": "Second part of the address",
            "type": "string",
            "nullable": true
          },
          "city": {
            "description": "City of the address",
            "type": "string",
            "nullable": true
          },
          "country": {
            "description": "Country of the address",
            "type": "string",
            "nullable": true
          },
          "state": {
            "description": "State of the address",
            "type": "string",
            "nullable": true
          },
          "zip": {
            "description": "Zip of the address",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataCheckboxValueApiDto": {
        "title": "Submission Data Checkbox Value",
        "description": "Submission data checkbox value response",
        "properties": {
          "values": {
            "description": "Values of the checkbox",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataCreditCardValueApiDto": {
        "title": "Submission Data CreditCard Value",
        "description": "Submission data credit card value response",
        "properties": {
          "card": {
            "description": "Number of the credit card",
            "type": "string",
            "nullable": true
          },
          "cardexp": {
            "description": "Expiration date of the credit card",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataDatetimeValueApiDto": {
        "title": "Submission Data Datetime Value",
        "description": "Submission data datetime value response",
        "properties": {
          "values": {
            "description": "Values of the datetime",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataFileValueApiDto": {
        "title": "Submission Data File Value",
        "description": "Submission data file value response",
        "properties": {
          "values": {
            "description": "Values of the file",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataMatrixValueApiDto": {
        "title": "Submission Data Matrix Value",
        "description": "Submission data matrix value response",
        "properties": {
          "values": {
            "description": "Values of the matrix",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": false
          }
        },
        "type": "object"
      },
      "SubmissionDataNameValueApiDto": {
        "title": "Submission Data Name Value",
        "description": "Submission data name value response",
        "properties": {
          "prefix": {
            "description": "Prefix of the name",
            "type": "string",
            "nullable": true
          },
          "first": {
            "description": "First name of the name",
            "type": "string",
            "nullable": true
          },
          "initial": {
            "description": "Initial of the name",
            "type": "string",
            "nullable": true
          },
          "middle": {
            "description": "Middle of the name",
            "type": "string",
            "nullable": true
          },
          "last": {
            "description": "Last name of the name",
            "type": "string",
            "nullable": true
          },
          "suffix": {
            "description": "Suffix of the name",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataProductValueApiDto": {
        "title": "Submission Data Product Value",
        "description": "Submission data product value response",
        "properties": {
          "chargeType": {
            "description": "ChargeType of the product",
            "type": "string",
            "nullable": true
          },
          "quantity": {
            "description": "Quantity of the product",
            "type": "string",
            "nullable": true
          },
          "total": {
            "description": "Total of the product",
            "type": "string",
            "nullable": true
          },
          "unitPrice": {
            "description": "UnitPrice of the product",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataRadioValueApiDto": {
        "title": "Submission Data Radio Value",
        "description": "Submission data radio value response",
        "properties": {
          "values": {
            "description": "Values of the radio",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataSelectValueApiDto": {
        "title": "Submission Data Select Value",
        "description": "Submission data select value response",
        "properties": {
          "values": {
            "description": "Values of the select",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "SubmissionDataSignatureValueApiDto": {
        "title": "Submission Data Signature Value",
        "description": "Submission data signature value response",
        "properties": {
          "values": {
            "description": "Values of the signature",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "FormSubmissionPreviewApiDto": {
        "title": "Form Submission Preview",
        "description": "Form submission preview response",
        "properties": {
          "id": {
            "description": "The ID of the submission",
            "type": "integer",
            "nullable": false
          },
          "formId": {
            "description": "The ID of the submission form",
            "type": "integer",
            "nullable": false
          },
          "timestamp": {
            "description": "Timestamp of the submission",
            "type": "string",
            "nullable": false
          },
          "data": {
            "description": "Data of the submission (equals null also if this field isn't requested). Shape depends on the dataFormat request parameter: 'legacy' (default) returns an object keyed by field id, where each value has field, label, type, internal_label, value and (when expandData=true) flat_value; 'standardized' returns an array of field objects matching GET /submissions/{id}. The example shows the legacy (default) shape.",
            "example": {
              "123456": {
                "field": "123456",
                "label": "Email Address",
                "type": "email",
                "internal_label": "email",
                "value": "john@example.com",
                "flat_value": "john@example.com"
              },
              "123457": {
                "field": "123457",
                "label": "Full Name",
                "type": "name",
                "internal_label": "full_name",
                "value": "John Smith",
                "flat_value": "John Smith"
              }
            },
            "nullable": true,
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/FormSubmissionPreviewLegacyDataApiDto"
                }
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FormSubmissionPreviewDataApiDto"
                }
              }
            ]
          },
          "prettyName": {
            "description": "Pretty name of the submission (equals null also if this field isn't requested)",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "FormSubmissionPreviewDataApiDto": {
        "title": "Form Submission Preview Data",
        "description": "Form submission preview data response",
        "properties": {
          "field": {
            "description": "The unique identifier of the field this data belongs to",
            "type": "string",
            "nullable": false
          },
          "label": {
            "description": "The display label/name of the field",
            "type": "string",
            "nullable": true
          },
          "type": {
            "description": "The field type (text, email, select, etc.)",
            "type": "string",
            "nullable": true
          },
          "internalLabel": {
            "description": "The internal label/alias of the field for API usage",
            "type": "string",
            "nullable": true
          },
          "displayValue": {
            "description": "The formatted display value of the field as it would appear to users",
            "type": "string",
            "nullable": true
          },
          "parsedValue": {
            "description": "The structured, parsed value of the field data based on field type. Only present when expandData=true.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/SubmissionDataNameValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataAddressValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataDatetimeValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataProductValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataCheckboxValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataRadioValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataFileValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataMatrixValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataSelectValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataSignatureValueApiDto"
              },
              {
                "$ref": "#/components/schemas/SubmissionDataCreditCardValueApiDto"
              }
            ]
          }
        },
        "type": "object"
      },
      "FormSubmissionPreviewLegacyDataApiDto": {
        "title": "Form Submission Preview Data (legacy)",
        "description": "Legacy form submission data item, keyed by field id in the response. Returned when dataFormat=legacy (the default).",
        "properties": {
          "field": {
            "description": "The unique identifier of the field this data belongs to",
            "type": "string",
            "nullable": false
          },
          "label": {
            "description": "The display label/name of the field",
            "type": "string",
            "nullable": true
          },
          "type": {
            "description": "The field type (text, email, select, etc.)",
            "type": "string",
            "nullable": true
          },
          "internal_label": {
            "description": "The internal label/alias of the field for API usage",
            "type": "string",
            "nullable": true
          },
          "value": {
            "description": "The field value. When expandData is not set this is the flat/raw value; when expandData=true this is the structured, parsed value.",
            "nullable": true
          },
          "flat_value": {
            "description": "The flat/raw value of the field. Only present when expandData=true.",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "FormSubmissionsListingApiDto": {
        "title": "Form Submissions Listing",
        "description": "Form submissions listing response",
        "properties": {
          "page": {
            "$ref": "#/components/schemas/PaginationApiDto"
          },
          "submissions": {
            "description": "Preview of form submission in list",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormSubmissionPreviewApiDto"
            },
            "nullable": true
          }
        },
        "type": "object"
      },
      "GetFormSubmissionsListApiDto": {
        "title": "Get Form Submissions List",
        "description": "Get form submissions list params",
        "properties": {
          "pageNumber": {
            "description": "Page to use when paginating through items.",
            "type": "integer",
            "minimum": 1,
            "nullable": true
          },
          "pageSize": {
            "description": "Number of items to return per page.",
            "type": "integer",
            "default": 50,
            "maximum": 500,
            "minimum": 10,
            "nullable": true
          },
          "order": {
            "description": "Order direction of results.",
            "type": "string",
            "default": "ASC",
            "enum": [
              "ASC",
              "DESC"
            ],
            "nullable": true
          },
          "keyword": {
            "description": "Keyword to search.",
            "type": "string",
            "nullable": true
          },
          "minTime": {
            "description": "Return submissions at and after given date/time - YYYY-MM-DD or YYYY-MM-DD HH:MM:SS expected (Based around Eastern Time).",
            "type": "string",
            "nullable": true
          },
          "maxTime": {
            "description": "Return submissions at and before given date/time - YYYY-MM-DD or YYYY-MM-DD HH:MM:SS expected (Based around Eastern Time).",
            "type": "string",
            "nullable": true
          },
          "search": {
            "description": "Array of search criteria to filter submissions by specific field values. Each criterion must include a fieldId and value. Maximum 10 search criteria allowed (index 0-9).",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchCriterionDto"
            },
            "example": [
              {
                "fieldId": "123456",
                "value": "john@example.com"
              },
              {
                "fieldId": "789012",
                "value": "New York"
              }
            ],
            "nullable": true
          },
          "data": {
            "description": "Flag to include submission data.",
            "type": "string",
            "nullable": true
          },
          "expandData": {
            "description": "Flag to expand submission data.",
            "type": "string",
            "nullable": true
          },
          "prettyName": {
            "description": "Flag to include pretty name.",
            "type": "string",
            "nullable": true
          },
          "dataFormat": {
            "description": "Shape of the 'data' field when data=true. 'legacy' (default): map keyed by field id with value/flat_value/internal_label. 'standardized': array of field objects matching GET /submissions/{id} with displayValue/parsedValue/internalLabel.",
            "type": "string",
            "default": "legacy",
            "enum": [
              "legacy",
              "standardized"
            ],
            "nullable": true
          }
        },
        "type": "object"
      }
    }
  },
  "tags": [
    {
      "name": "Submissions",
      "description": "Submissions are the entries collected by your forms. Use these endpoints to create a submission, list submissions across all forms or for a specific form, count submissions, retrieve a single submission's data, edit or delete a submission, download uploaded files, and generate presigned URLs for direct file uploads. Results support pagination, date ranges, and field-level search."
    },
    {
      "name": "Classic",
      "description": "Classic"
    }
  ]
}
```