Contact Us
Quote Request
  • App Support
    • Knowledge Base
      • API Documentation
      • Classic Portal Documentation
      • App Developer Account Info
      • Video Tutorials – Classic
      • Onboarding Documentation
      • New Portal Documentation
      • Video Tutorials – New
      • App Version Update Notes
    • App Success Tips
      • App Launch Success Guide​
      • Populate Your App For Launch
      • Train Your App Administrators
      • Prepare and Plan Your Marketing Launch Activities
      • Keep Your App Fresh
      • Consistently Remind Your Community about Your App
      • Turn Your App Administrators into Super-Users
      • Ensure Your App Is a Must-Have for Your Community
  • Additional Services
    • Additional Training
    • Content & Design
      • Blog Posts
      • Infographics
      • Content Packages
      • Assessments
      • Editorial Services
      • Whiteboard Video
    • Marketing Support
Menu
  • App Support
    • Knowledge Base
      • API Documentation
      • Classic Portal Documentation
      • App Developer Account Info
      • Video Tutorials – Classic
      • Onboarding Documentation
      • New Portal Documentation
      • Video Tutorials – New
      • App Version Update Notes
    • App Success Tips
      • App Launch Success Guide​
      • Populate Your App For Launch
      • Train Your App Administrators
      • Prepare and Plan Your Marketing Launch Activities
      • Keep Your App Fresh
      • Consistently Remind Your Community about Your App
      • Turn Your App Administrators into Super-Users
      • Ensure Your App Is a Must-Have for Your Community
  • Additional Services
    • Additional Training
    • Content & Design
      • Blog Posts
      • Infographics
      • Content Packages
      • Assessments
      • Editorial Services
      • Whiteboard Video
    • Marketing Support

API Documentation

  • API Documentation
  • Assessments & Quiz API Sample
  • Forms & Reporting API Sample
  • Side Menu API Sample

Classic Portal Documentation

  • Advantages
  • Alerts
  • Assessments and Quizzes
  • Checklists
  • Content Authoring Tool
  • Creating a Quiz
  • eGuide Library
  • Events
  • FAQ Module
  • Form Elements Breakdown
  • How to Create a Scored Assessment
  • Logging In to Your Portal
  • Module Access Codes
  • News
  • PDF Library
  • Reporting and Forms
  • Resources Module
  • Text Module / Welcome Message
  • User Management
  • Videos

App Developer Account Info

  • Apple Developer Program Letter Request
  • Enrolling in the Apple Developer Program
  • Getting Started with Developer Accounts
  • Granting QuickSeries Access to Your App Store Connect
  • Granting QuickSeries Access to Your Google Play Console
  • Register for a Google Play Developer account
  • Transferring Your App: How to Accept the Transfer
  • Transferring Your App: How to Initiate the Transfer

Video Tutorials - Classic

  • FAQ Module
  • Module Access Codes
  • News Module
  • Reports and Forms

Onboarding Documentation

  • 12 Steps of Onboarding
  • Installing Your Test App on Android (Firebase)
  • Installing Your Test App on iOS (TestFlight)

New Portal Documentation

  • Alerts
  • Assessments
  • Checklists
  • eGuide Library / Bundles
  • FAQ
  • Form Elements Breakdown
  • Forms & Reporting
  • Make Your Plan
  • Maps
  • Module Access Codes
  • News
  • NWS / FEMA Alerts
  • PDF Library
  • Privacy Policy and Terms and Conditions editor
  • QuickConnect Workspaces
  • Resources
  • Side Menu Customization
  • User Management
  • User Onboarding
  • Video Library
  • Welcome Message

Video Tutorials - New

  • Access Codes
  • Alerts Module
  • App User Onboarding
  • Assessment & Quiz Module
  • Checklist Module
  • FAQ Module
  • Library Module
  • Make Your Plan Module
  • Maps: How to create zones
  • News Module
  • NWS and FEMA Alerts
  • Privacy Policy and Terms and Conditions editor
  • QuickConnect Workspaces
  • Reporting Module
  • Resources Module
  • Side Menu Customization
  • Video Library Module
  • Welcome Message Module

App Success Tips

  • App Launch Success Guide​
  • Consistently Remind Your Community about Your App
  • Ensure Your App Is a Must-Have for Your Community
  • Keep Your App Fresh
  • Populate Your App For Launch
  • Prepare and Plan Your Marketing Launch Activities
  • Train Your App Administrators
  • Turn Your App Administrators into Super-Users

App Version Update Notes

  • Version 3.11.0
  • Version 3.11.2
  • Version 3.12.2
  • Version 3.13.2
  • Version 3.7.1
  • Version 3.8.0
  • Version 3.9.0
  • Home
  • Knowledge Base
  • API Documentation

Forms & Reporting API Sample

Table of Contents
  • Full payload example
  • Definition payload example
  • Short text definition example
  • Number definition example
  • File upload definition example
  • Section definition example
  • Line separator definition example
  • Dropdown definition example
  • Checklist definition example
  • Radio list definition example
  • Address definition example
  • Phone definition example
  • Email definition example
  • Date definition example
  • Time definition example
Print Friendly, PDF & EmailQuickPrint

The forms and reporting API allows you to create and edit forms as well as submit and export form data.

Forms are created from the admin portal using our drag and drop form editor. You can use up to 14 different widgets to create and structure your forms.

If you already have a form building tool (such as Wufoo) and want to automatically generate an equivalent form in your App, you may build a tool to create and publish a QuickSeries compatible form.

Below, you will see payload examples that you must follow in order to successfully create a form in your QuickSeries App.

Full payload example

KeyDescriptionTypeRequiredPossible values
eid stringOnly for a PUT request.This value is provided to you after creating a new item.
title stringtrueAny string
description stringfalseMust be valid HTML ideally generated by Quill editor to maintain styling compatibility: https://quilljs.com/
definition stringtrueThis property contains the structure of the form and must be a “stringified” JSON object. See below for each form widget schemas.
status stringtruedraft, published
full_contentForms can be configured to forward an email notification to any admin portal user. If a user is selected and If full_content is set to true, it will include the full content of the submitted report in that notification email. Otherwise, the email will simply contain the notification message and a link to the report.booleantruetrue, false
notificationsForms can be configured to forward an email notification to any portal user. Only the emails of portal users can be added here.arrayNoAn array of portal user emails.

 

I.e.:

[
“john.doe@domain.com”
]
{
  "eid": "0045ffae-24bd-4e7d-bc33-1761817cebed",
  "title": "Example payload",
  "description": { "en": "<p>Example WYSIWYG description generated by Quill editor.</p>" },
  "definition": "[{\"eid\":\"82e9c53c-b887-4f36-a98f-4d553f333c2f\",\"type\":\"section\",\"content\":[[{\"eid\":\"1760ac5d-5fde-4570-99c8-6c00616a3752\",\"type\":\"short-text-field\",\"label\":\"Short Text\",\"icon\":\"icon--short-text-field\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled short text\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"dsadasdasdas\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"placeholder\":{\"name\":\"Placeholder text\",\"value\":\"sadasdasdasd\",\"type\":\"text\",\"required\":false,\"info\":\"Enter example text to help users fill out this field. The text will disappear once users start typing.\"},\"defaultValue\":{\"name\":\"Default Value\",\"value\":\"dasdasd\",\"type\":\"default-text\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"},\"characterLimits\":{\"name\":\"Character Limits\",\"min\":3,\"max\":10,\"required\":true,\"type\":\"size-range\",\"info\":\"Enter the minimum and/or maximum number of characters allowed in this field.\"}},\"hasErrors\":[]}]],\"label\":\"Section\",\"icon\":\"icon--section\",\"allowedTypes\":[\"line-separator\",\"short-text-field\",\"long-text-field\",\"number-field\",\"file-upload\",\"dropdown-list\",\"multiple-choice\",\"single-choice\",\"address\",\"phone-number\",\"email-field\",\"date-picker\",\"time-picker\"],\"properties\":{\"title\":{\"name\":\"Section title\",\"value\":\"Untitled section\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a title for this element.\"},\"collapsible\":{\"name\":\"Section collapse\",\"value\":false,\"type\":\"checkbox\",\"required\":false,\"info\":\"Allow the user to collapse and expand this section.\"},\"description\":{\"name\":\"Instructions text\",\"value\":\"fefwefwefwe\",\"type\":\"textarea\",\"info\":\"Enter any notes or instructions to help users fill out this field.\",\"required\":false}},\"hasErrors\":[]},{\"eid\":\"cb31e0dd-357d-4a23-a30d-0e0ae24b79cb\",\"type\":\"long-text-field\",\"label\":\"Long Text\",\"icon\":\"icon--long-text-field\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Label\",\"value\":\"Untitled long text\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"efwfwe\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"placeholder\":{\"name\":\"Placeholder text\",\"value\":\"fefwefwef\",\"type\":\"text\",\"required\":false,\"info\":\"Enter example text to help users fill out this field. The text will disappear once users start typing.\"},\"defaultValue\":{\"name\":\"Default Value\",\"value\":\"fewfwef\",\"type\":\"default-textarea\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"},\"characterLimits\":{\"name\":\"Character Limits\",\"min\":1,\"max\":456,\"required\":true,\"type\":\"size-range\",\"info\":\"Enter the minimum and/or maximum number of characters allowed in this field.\"}},\"hasErrors\":[]},{\"eid\":\"39ef0e3d-5fbe-48a1-a649-b443f393dbe1\",\"type\":\"number-field\",\"label\":\"Number\",\"icon\":\"icon--number-input\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled number\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"dqwdqwdq\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"placeholder\":{\"name\":\"Placeholder text\",\"value\":\"dqwdqwdq\",\"type\":\"text\",\"required\":false,\"info\":\"Enter example text to help users fill out this field. The text will disappear once users start typing.\"},\"defaultValue\":{\"name\":\"Default Value\",\"value\":3,\"type\":\"default-number\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"},\"numberLimits\":{\"name\":\"Number range\",\"min\":1,\"max\":11,\"required\":true,\"type\":\"number-range\",\"info\":\"Enter the minimum and/or maximum number range required for this field.\"},\"unit\":{\"name\":\"Unit\",\"value\":\"meters\",\"type\":\"unit\",\"required\":true,\"info\":\"Enter the unit of measure required for this field. The unit will become part of the answer for users.\"}},\"hasErrors\":[]},{\"eid\":\"34186314-c9e1-4dd3-9d41-270b5c225e8a\",\"type\":\"file-upload\",\"label\":\"File Upload\",\"icon\":\"icon--file-upload\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled file\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"fwefwef\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"}},\"hasErrors\":[]},{\"eid\":\"21254c0d-c9ef-451e-b1a0-074332865512\",\"type\":\"dropdown-list\",\"label\":\"Dropdown\",\"icon\":\"icon--dropdown-list\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled dropdown\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"fwefwefw\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"defaultOptionValue\":{\"name\":\"Default Value\",\"value\":\"Option 2\",\"type\":\"default-option\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"},\"options\":{\"name\":\"Options\",\"value\":[{\"label\":\"Option 1\",\"value\":\"\"},{\"label\":\"Option 2\",\"value\":\"\"}],\"type\":\"options\",\"required\":true,\"info\":\"Create a list of options for users to choose from. Use the plus and minus to add or delete options.\"}},\"hasErrors\":[]},{\"eid\":\"5bce087d-f9ee-4597-8051-ef2a9bac330d\",\"type\":\"multiple-choice\",\"label\":\"Checklist\",\"icon\":\"icon--multiple-choice\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled checklist\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"fwefwef\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"defaultOptionsValues\":{\"name\":\"Default Values\",\"value\":[\"Option 2\"],\"type\":\"default-options\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"},\"options\":{\"name\":\"Options\",\"value\":[{\"label\":\"Option 1\",\"value\":\"\"},{\"label\":\"Option 2\",\"value\":\"\"}],\"type\":\"checkbox-group\",\"required\":true,\"info\":\"Enter each element to select from.\"}},\"hasErrors\":[]},{\"eid\":\"34bb8516-acf3-4c8f-85ee-4ec9433c3215\",\"type\":\"single-choice\",\"label\":\"Radio list\",\"icon\":\"icon--single-choice\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled single choice\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"fwefwe\",\"type\":\"textarea\",\"required\":false,\"info\":\"Use this field to provide the user with instructions for this field.\"},\"defaultOptionValue\":{\"name\":\"Default Value\",\"value\":\"Option 1\",\"type\":\"default-option\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"},\"options\":{\"name\":\"Options\",\"value\":[{\"label\":\"Option 1\",\"value\":\"\"},{\"label\":\"Option 2\",\"value\":\"\"}],\"type\":\"options\",\"required\":true,\"info\":\"Create a list of options for users to choose from. Use the plus and minus to add or delete options.\"}},\"hasErrors\":[]},{\"eid\":\"73cf153c-ab7c-416e-88ed-4c396be879a5\",\"type\":\"address\",\"label\":\"Address\",\"icon\":\"icon--address\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled address\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"fwefwef\",\"type\":\"textarea\",\"required\":false,\"info\":\"Use this field to provide the user with instructions for this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"}},\"hasErrors\":[]},{\"eid\":\"f38e6fe9-7c73-4e67-ae59-1402ecb6c4dd\",\"type\":\"phone-number\",\"label\":\"Phone\",\"icon\":\"icon--phone-number\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled phone\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"fwefwef\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"placeholder\":{\"name\":\"Placeholder text\",\"value\":\"12312321\",\"type\":\"text\",\"required\":false,\"info\":\"Enter example text to help users fill out this field. The text will disappear once users start typing.\"},\"defaultValue\":{\"name\":\"Default value\",\"value\":\"123123\",\"type\":\"default-phone\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"extension\":{\"name\":\"Extension\",\"value\":\"123\",\"type\":\"text\",\"required\":false,\"info\":\"Enter a extension field's default value.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Configure this field to be mandatory when the user submits this form.\"}},\"hasErrors\":[]},{\"eid\":\"01df11c1-14cd-4f7e-ac81-e5966d4e0c53\",\"type\":\"email-field\",\"label\":\"Email\",\"icon\":\"icon--email\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled email\",\"type\":\"text\",\"required\":true,\"info\":\"Enter a name or title for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"dqwdqwdq\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"placeholder\":{\"name\":\"Placeholder text\",\"value\":\"dqwdqwdq\",\"type\":\"text\",\"required\":false,\"info\":\"Enter example text to help users fill out this field. The text will disappear once users start typing.\"},\"defaultValue\":{\"name\":\"Default Value\",\"value\":\"email@domain.com\",\"type\":\"default-email\",\"required\":true,\"info\":\"Enter a default answer that will appear in this field.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Require users to fill out this field before they can submit the form.\"}},\"hasErrors\":[]},{\"eid\":\"8e11d52b-98ce-4f49-a3ec-a846dd9c6229\",\"type\":\"date-picker\",\"label\":\"Date\",\"icon\":\"icon--date-picker\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field label\",\"value\":\"Untitled date\",\"type\":\"text\",\"required\":true,\"info\":\"Add a label for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"dqwdqd\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"defaultValue\":{\"name\":\"Predefined Value\",\"value\":\"2022-03-17T04:00:00.000Z\",\"type\":\"default-date\",\"required\":true,\"info\":\"Add a default value for this field that the user will see and be able to change.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Prevent the user from submitting the form if this field is empty.\"},\"dateRange\":{\"name\":\"Date Range\",\"min\":\"2022-03-08T05:00:00.000Z\",\"max\":\"2022-03-31T04:00:00.000Z\",\"required\":true,\"type\":\"date-range\",\"info\":\"Select the date range that the user can choose from.\"}},\"hasErrors\":[]},{\"eid\":\"0908e23e-b606-4e1e-8af3-ff03dc9e4450\",\"type\":\"time-picker\",\"label\":\"Time\",\"icon\":\"icon--time-picker\",\"allowedTypes\":[],\"properties\":{\"label\":{\"name\":\"Field Label\",\"value\":\"Untitled time\",\"type\":\"text\",\"required\":true,\"info\":\"Add a label for this field.\"},\"instructions\":{\"name\":\"Instructions\",\"value\":\"dqwdqw\",\"type\":\"textarea\",\"required\":false,\"info\":\"Enter any notes or instructions to help users fill out this field.\"},\"defaultValue\":{\"name\":\"Predefined Value\",\"value\":\"16:19\",\"type\":\"default-time\",\"required\":true,\"info\":\"Add a default value for this field that the user will see and be able to change.\"},\"required\":{\"name\":\"Required field\",\"value\":true,\"type\":\"checkbox\",\"required\":false,\"info\":\"Prevent the user from submitting the form if this field is empty.\"},\"timeRange\":{\"name\":\"Time Range\",\"min\":\"08:00\",\"max\":\"17:00\",\"type\":\"time-range\",\"required\":true,\"meridian\":true,\"info\":\"Select the time range that the user can choose from.\"}},\"hasErrors\":[]}]",
  "status": "draft",
  "full_content": true,
  "updated_at": "2022-03-10T16:32:56.346Z",
  "notifications": ["portal.user@domain.com"]
}

Definition payload example

The definition key defined above is a “stringified” JSON that contains the definition/configuration of each form component. Below you will find the details about each definition keys.

KeyDescriptionTypeRequiredPossible valuesApplied to components
eidThe EID must be generated by the user of the API using the UUID v4 algorithm.stringfalseUUID v4 stringAll
typeThis is the type of component available when creating a form.stringtrueshort-text-field, long-text-field, number-field, file-upload, section, line-separator, dropdown-list, multiple-choice, single-choice, address, phone-number, email-field, date-picker, time-picker.All
labelThe label value is the input label, commonly displayed above the input itself.stringfalseAny stringAll
iconThis is a constant value that must be added to each component definition. Each component type has its own possible value.stringfalseicon–short-text-field, icon–long-text-field, icon–number-input, icon–file-upload, icon–section, line-separator, icon–dropdown-list, icon–multiple-choice, icon–single-choice, icon–address, icon–phone-number, icon–email, icon–date-picker, icon–time-pickerAll
allowedTypesThis key is reserved for the section component.arrayfalse[] (for all components other than section) or [“line-separator”, “short-text-field”, “long-text-field”, “number-field”, “file-upload”, “dropdown-list”, “multiple-choice”, “single-choice”, “address”, “phone-number”, “email-field”, “date-picker”, “time-picker”] (for the Section component).All
contentThis key contains the content of a section. Simply add any component definition in here.arraytrue (only for section components)Any component definition (see below)Section
propertiesThis key contains all the possible properties that configure the behaviour of each component. For example, this is where you will define whether a value for a component (i.e.: short text) is required. Each component can have a different set of properties. Not all properties are compatible with all components.object or null

 

(only the Line separator component should have a value of null here).

falseAny property definition (see below)All

All properties contain UI logic for the form builder in our admin portal. If a property object is not passed, a default value for each property will be used, if a property object is passed, see the table below to check what is required when creating a new form from the API.

Here is a list of all properties and which component they belong to and whether they are required or optional:

PropertiesShort textLong textNumberFile uploadSectionLine separatorDropdownChecklistRadio listAddressPhoneEmailDateTime
labelREQUIREDREQUIREDREQUIREDREQUIRED  REQUIREDREQUIREDREQUIREDREQUIREDREQUIREDREQUIREDREQUIREDREQUIRED
instructionsOPTIONALOPTIONALOPTIONALOPTIONAL  OPTIONALOPTIONALOPTIONALOPTIONALOPTIONALOPTIONALOPTIONALOPTIONAL
placeholderOPTIONALOPTIONALOPTIONAL       OPTIONALOPTIONALOPTIONALOPTIONAL
defaultValueREQUIREDREQUIREDREQUIRED       REQUIREDREQUIREDREQUIREDREQUIRED
requiredOPTIONALOPTIONALOPTIONALOPTIONAL  OPTIONALOPTIONALOPTIONALOPTIONALOPTIONALOPTIONALOPTIONALOPTIONAL
characterLimitsREQUIREDREQUIRED            
numberLimits  REQUIRED           
unit  REQUIRED           
title    REQUIRED         
collapsible    OPTIONAL         
description    OPTIONAL         
options      REQUIREDREQUIREDREQUIRED     
defaultOptionValue      REQUIRED only if enabled. REQUIRED only if enabled.     
defaultOptionsValues       REQUIRED only if enabled.      
extension          OPTIONAL   
dateRange            REQUIRED 
timeRange             REQUIRED

properties.label

The label property represents the main component label.

  • Type: object
  • Required: true
  • Applies to the following components: Short text, Long text, Number, File upload, Dropdown, Checklist, Radio list, Address, Phone, Email, Date, Time
PropertiesTypeRequiredPossible valuesDescription
namestringtrueField label 
valuestringtrueAny valuesThis key contains the input label value.
typestringtruetext 
requiredbooleantruetrue, false 
infostringtrueEnter a name or title for this field. 

properties.instructions

The instructions property represents text below the main component label.

  • Type: object
  • Required: true
  • Applies to the following components: Short text, Long text, Number, File upload, Dropdown, Checklist, Radio list, Address, Phone, Email, Date, Time
PropertiesTypeRequiredPossible valuesDescription
namestringtrueInstructions 
valuestringfalseAny valuesThis key contains the input instruction value.
typestringtruetextarea 
requiredbooleantruetrue, false 
infostringtrueEnter any notes or instructions to help users fill out this field. 

properties.placeholder

The placeholder property represents placeholder text displayed in some components.

  • Type: object
  • Required: true
  • Applies to the following components: Short text, Long text, Number, Phone, Email, Date, Time
PropertiesTypeRequiredPossible valuesDescription
namestringtruePlaceholder text 
valuestringfalseAny valuesThis key contains the input placeholder value.
typestringtruetext 
requiredbooleantruetrue, false 
infostringtrueEnter example text to help users fill out this field. The text will disappear once users start typing. 

properties.defaultValue

The defaultValue property represents the default value that should be entered by default when a user loads the form. Unless changed by the user, it should be submitted as is to the API.

  • Type: object
  • Required: true
  • Applies to the following components: Short text, Long text, Number, Phone, Email, Date, Time
PropertiesTypeRequiredPossible valuesDescription
namestringtrueDefault Value 
valuestringfalseAny values 
typestringtruedefault-text 
requiredbooleanfalsetrue, false 
infostringtrueRequire users to fill out this field before they can submit the form. 

properties.required

The required property is used to validate whether a form component should have a value before submitting the form.

  • Type: object
  • Required: true
  • Applies to the following components: Short text, Long text, Number, File upload, Dropdown, Checklist, Radio list, Address, Phone, Email, Date, Time
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueRequired field 
valuestringtruetrue, falseThis key defines whether an input is required or optional.
typestringtruecheckbox 
requiredbooleantruetrue, false 
infostringtrueRequire users to fill out this field before they can submit the form. 

properties.characterLimits

The characterLimits property is used to set a character limits (min and max) for some components.

  • Type: object
  • Required: true
  • Applies to the following components: Short text, Long text
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueRequired field 
minnumbertrueAny number 
maxnumbertrueAny number bigger than min 
typestringtruesize-range 
requiredbooleantruetrue, false 
infostringtrueEnter the minimum and/or maximum number of characters allowed in this field. 

properties.numberLimits

The characterLimits property is used to set number limits (min and max) on the number component.

  • Type: object
  • Required: true
  • Applies to the following component: Number
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueNumber range 
minnumbertrueAny number 
maxnumbertrueAny number bigger than min 
typestringtruenumber-range 
requiredbooleantruetrue, false 
infostringtrueEnter the minimum and/or maximum number range required for this field. 

properties.unit

The unit property is used to append a unit of measure to the number entered in the number component.

  • Type: object
  • Required: true
  • Applies to the following component: Number
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueUnit 
valuestringtrueAny string 
typestringtrueunit 
requiredbooleantruetrue, false 
infostringtrueEnter the unit of measure required for this field. The unit will become part of the answer for users. 

properties.title

The title property is used to give a title to a section component.

  • Type: object
  • Required: true
  • Applies to the following component: Section
PropertiesTypeProperty is requiredPossible valuesDescription
titlestringtrueSection title 
valuestringtrueAny string 
typestringtruetext 
requiredbooleantruetrue, false 
infostringtrueEnter a title for this element. 

properties.collapsible

The collapsible property is used to determine whether a section should be collapsible or not.

  • Type: object
  • Required: true
  • Applies to the following component: Section
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueSection collapse 
valuestringtruetrue, false 
typebooleantruecheckbox 
requiredbooleantruetrue, false 
infostringtrueAllow the user to collapse and expand this section. 

properties.description

The description property is text that appears below the section title.

  • Type: object
  • Required: true
  • Applies to the following component: Section
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueInstructions text 
valuestringtrueAny string 
typestringtruetextarea 
requiredbooleantruetrue, false 
infostringtrueEnter any notes or instructions to help users fill out this field. 

properties.defaultOptionValue

The defaultOptionValue property is the default selected value for dropdown and radio list components. You must provide a value defined in the options definition.

  • Type: object
  • Required: true
  • Applies to the following components: Dropdown, Radio list
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueDefault Value 
valuestringtrueAny values defined in the properties.options.value array. 
typestringtruedefault-option 
requiredbooleantruetrue, false 
infostringtrueEnter a default answer that will appear in this field. 

properties.defaultOptionsValues

The defaultOptionsValues property is the default selected value(s) for checklist components. You must provide one or more values defined in the options definition.

  • Type: object
  • Required: true
  • Applies to the following component: Checklist
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueDefault Value 
valuearraytrueAny values defined in the properties.options.valuearray.Example:

 

“defaultOptionsValues”: {
“name”: “Default Values”,
“value”: [“Red”, “Yellow”],
“type”: “default-options”,
“required”: true,
“info”: “Enter a default answer that will appear in this field.”
},
typestringtruedefault-options 
requiredbooleantruetrue, false 
infostringtrueEnter a default answer that will appear in this field. 

properties.options

The options property defines all options you can select from in the dropdown, radio list and checklist components.

  • Type: object
  • Required: true
  • Applies to the following components: Dropdown, Radio list, Checklist
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueOptions 
valuearraytrue{
label: string,
value: string
}
 
typestringtrueoptions 
requiredbooleantruetrue, false 
infostringtrueCreate a list of options for users to choose from. Use the plus and minus to add or delete options. 

properties.extensions

The extensions property defines whether a phone extension field should be displayed.

  • Type: object
  • Required: true
  • Applies to the following component: Phone
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueExtension 
valuestringtrueAny stringPhone number validation is not applied server side in order to allow international phone numbers.
typestringtruetext 
requiredbooleantruetrue, false 
infostringtrueEnter a extension field’s default value. 

properties.dateRange

The dateRange property defines the range within which the user can select a date.

  • Type: object
  • Required: true
  • Applies to the following component: Date
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueDate Range 
minstringtrueThe ISO 8601 date.I.e.: 2022-03-08T05:00:00.000Z
maxstringtrueA date after the min date. 
typestringtruedate-range 
requiredbooleantruetrue, false 
infostringtrueSelect the date range that the user can choose from. 

properties.timeRange

The timeRange property defines the range within which the user can select a time.

  • Type: object
  • Required: true
  • Applies to the following component: Time
PropertiesTypeProperty is requiredPossible valuesDescription
namestringtrueTime Range 
minstringtrueMilitary formatted time.I.e.:

 

  • 08:00
  • 17:46
maxstringtrueA time after the min time. 
typestringtruetime-range 
requiredbooleantruetrue, false 
meridianbooleantruetrue, false 
infostringtrueSelect the time range that the user can choose from. 

Short text definition example

The short text widget is a simple text input. You can configure that input with a label, instructions, a placeholder, a default value, whether it should be a required field or not and the character length limitation.

{
  "eid": "1760ac5d-5fde-4570-99c8-6c00616a3752",
  "type": "short-text-field",
  "label": "Short Text",
  "icon": "icon--short-text-field",
  "allowedTypes": [],
  "properties": {
    "label": {
      "name": "Field label",
      "value": "Example short text label",
      "type": "text",
      "required": true,
      "info": "Enter a name or title for this field."
    },
    "instructions": {
      "name": "Instructions",
      "value": "Example short text instructions.",
      "type": "textarea",
      "required": false,
      "info": "Enter any notes or instructions to help users fill out this field."
    },
    "placeholder": {
      "name": "Placeholder text",
      "value": "Example short text placeholder",
      "type": "text",
      "required": false,
      "info": "Enter example text to help users fill out this field. The text will disappear once users start typing."
    },
    "defaultValue": {
      "name": "Default Value",
      "value": "Example short text default value.",
      "type": "default-text",
      "required": true,
      "info": "Enter a default answer that will appear in this field."
    },
    "required": {
      "name": "Required field",
      "value": true,
      "type": "checkbox",
      "required": false,
      "info": "Require users to fill out this field before they can submit the form."
    },
    "characterLimits": {
      "name": "Character Limits",
      "min": 3,
      "max": 10,
      "required": true,
      "type": "size-range",
      "info": "Enter the minimum and/or maximum number of characters allowed in this field."
    }
  },
  "hasErrors": []
}

Long text definition example

The long text widget is a simple text box (or text area). You can configure that input with a label, instructions, a placeholder, a default value, whether it should be a required field or not and the character length limitation.

{
  "eid": "cb31e0dd-357d-4a23-a30d-0e0ae24b79cb",
  "type": "long-text-field",
  "label": "Long Text",
  "icon": "icon--long-text-field",
  "allowedTypes": [],
  "properties": {
    "label": {
      "name": "Label",
      "value": "Example long text label",
      "type": "text",
      "required": true,
      "info": "Enter a name or title for this field."
    },
    "instructions": {
      "name": "Instructions",
      "value": "Example long text instructions.",
      "type": "textarea",
      "required": false,
      "info": "Enter any notes or instructions to help users fill out this field."
    },
    "placeholder": {
      "name": "Placeholder text",
      "value": "Example long text placeholder",
      "type": "text",
      "required": false,
      "info": "Enter example text to help users fill out this field. The text