HeyForm · Schema

HeyForm Submission

Schema for a HeyForm form submission, including respondent answers, hidden fields, and calculated variables.

FormsSurveysQuizzesPollsConversational FormsOpen SourceWebhooksNo-CodeForm BuilderSelf-Hosted

Properties

Name	Type	Description
id	string	Unique submission identifier.
formId	string	Identifier of the form this submission belongs to.
formName	string	Display name of the form at the time of submission.
teamId	string	Identifier of the workspace that owns the form.
title	string	Human-readable title for the submission (typically the form name).
category	string	Inbox category for the submission.
status	string	Whether the submission data is stored on the server.
answers	array	Array of respondent answers, one per answered field.
hiddenFields	array	Pre-populated hidden field values included in the submission.
variables	array	Calculated variable values at the time of submission (e.g. quiz scores).
ip	string	IP address of the respondent.
userAgent	string	User-agent string of the respondent's browser.
startAt	integer	Unix timestamp when the respondent opened the form.
endAt	integer	Unix timestamp when the respondent submitted the form.
createdAt	string	ISO 8601 creation timestamp.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api-evangelist.github.io/heyform/json-schema/heyform-submission.json",
  "title": "HeyForm Submission",
  "description": "Schema for a HeyForm form submission, including respondent answers, hidden fields, and calculated variables.",
  "type": "object",
  "required": ["id", "formId", "answers"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique submission identifier.",
      "example": "sub_abc123"
    },
    "formId": {
      "type": "string",
      "description": "Identifier of the form this submission belongs to."
    },
    "formName": {
      "type": "string",
      "description": "Display name of the form at the time of submission."
    },
    "teamId": {
      "type": "string",
      "description": "Identifier of the workspace that owns the form."
    },
    "title": {
      "type": "string",
      "description": "Human-readable title for the submission (typically the form name)."
    },
    "category": {
      "type": "string",
      "description": "Inbox category for the submission.",
      "enum": ["inbox", "spam", "archived"]
    },
    "status": {
      "type": "string",
      "description": "Whether the submission data is stored on the server.",
      "enum": ["public", "private"]
    },
    "answers": {
      "type": "array",
      "description": "Array of respondent answers, one per answered field.",
      "items": {
        "$ref": "#/definitions/SubmissionAnswer"
      }
    },
    "hiddenFields": {
      "type": "array",
      "description": "Pre-populated hidden field values included in the submission.",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "value": { "type": "string" }
        }
      }
    },
    "variables": {
      "type": "array",
      "description": "Calculated variable values at the time of submission (e.g. quiz scores).",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "kind": { "type": "string", "enum": ["number", "text"] },
          "value": {}
        }
      }
    },
    "ip": {
      "type": "string",
      "description": "IP address of the respondent.",
      "example": "203.0.113.42"
    },
    "userAgent": {
      "type": "string",
      "description": "User-agent string of the respondent's browser."
    },
    "startAt": {
      "type": "integer",
      "description": "Unix timestamp when the respondent opened the form."
    },
    "endAt": {
      "type": "integer",
      "description": "Unix timestamp when the respondent submitted the form."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 creation timestamp."
    }
  },
  "definitions": {
    "SubmissionAnswer": {
      "type": "object",
      "required": ["id"],
      "description": "A single answer within a submission.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The field identifier this answer corresponds to."
        },
        "title": {
          "type": "string",
          "description": "The question text of the field at the time of submission."
        },
        "kind": {
          "type": "string",
          "description": "Field type (see FormField.kind for possible values).",
          "enum": [
            "short_text", "long_text", "multiple_choice", "picture_choice",
            "yes_no", "rating", "opinion_scale", "date", "time", "number",
            "email", "url", "phone_number", "file_upload", "payment", "signature"
          ]
        },
        "value": {
          "description": "The respondent's answer. Type depends on field kind.",
          "oneOf": [
            {
              "title": "Text answer (short_text, long_text, email, url, phone_number, date, time)",
              "type": "string"
            },
            {
              "title": "Numeric answer (number, rating, opinion_scale)",
              "type": "number"
            },
            {
              "title": "Boolean answer (yes_no)",
              "type": "boolean"
            },
            {
              "title": "Multiple selection answer (multiple_choice, picture_choice)",
              "type": "array",
              "items": { "type": "string" }
            },
            {
              "title": "Payment answer",
              "type": "object",
              "properties": {
                "amount": { "type": "number" },
                "currency": { "type": "string" },
                "clientSecret": { "type": "string" }
              }
            },
            {
              "title": "File upload answer",
              "type": "object",
              "properties": {
                "filename": { "type": "string" },
                "url": { "type": "string", "format": "uri" },
                "size": { "type": "integer" }
              }
            }
          ]
        }
      }
    }
  }
}