Introduction

This API request is used to create a new form or make changes to an existing form.

Implementation tip: use GetFormDefinition to pull down the existing form structure if you are building a similar form.

This request’s JSON format varies for different type of forms and several types of fields. Aggregate field types and repeated fields with non-unique shortnames are not supported.

Getting Started

All API requests require an authorization token – reference our Authentication page for more information

API Structure

POST api/integration/SaveFormDesign

Required Request Parameters – All Forms

Name	Location	Value Options	Description
Authorization token	Header		See Login Authentication API documentation
Operation	Body	"Insert","Update"	Indicate if the API request is to create or update an existing Form.
PartialSuccess	Body	"True", "False"	Flag used when updating an existing form
RequestNo	Body		Recommended unique for each request, visible within the UI for troubleshooting.
FormID	Body	Leave blank on new form creation	GUID that can be used in other API requests.
FormName	Body	Required	Name of form that will be visible within the UI
Type	Body	Type : Form Type • 0 : Check • 1 : Audit • 2 : Questionnaire	See the Form Definition Page for information on when to use the different Form Types. Each Form Type corresponds to a numerical value - the numerical value is passed in the API request
Version	Body	New form: "0.1" Existing form: current value.	Version numbers are incremented automatically for existing forms, all new forms start at version 0.1
Resource ID	Body	""	GUID exposed in GetResources API response, value is optional.
Resource Name	Body		The name of the Resource within the UI.
Field Information	Body		See Below Table – will vary by Form Type and Field type.

Field Information Parameters – Check Type Form

The table below outlines the different role each value used within the different field types plays.

Name	Required	Value Options	Description
Type	Required	Type : Field Type • 15 : Identifier • 5 : Text • 6 : Paragraph • 7 : Select One • 8 : Select Multiple • 9 : Numeric • 10 : Date • 11 : Time • 12 : Date & Time	Field types are used to format how the user will provide their answer to a field – a free text entry, picking one or more options from a drop down etc. Each field type corresponds to a numerical value - the numerical value is passed in the API request.
ShowMinMax	Conditionally Required	"True"," False"	Used only on Numeric fields, makes the ranges set for Min and Max visible to the user.
ShowTarget	Conditionally Required	"True"," False"	Used only on Numeric fields, makes the target value set visible to the user.
IsIntegrated	Conditionally Required	"True"," False"	Used only for Numeric fields enabled with BlueTherm hardware.
DependencyRule	Required	null	Covered in Advanced API Integration Technical Specification Document.
ExpressionRule	Required	null	Covered in Advanced API Integration Technical Specification Document.
FailsForm	Required	"True"," False"	Indicates if a non-compliant value should result in the entire form being marked as non-compliant.
AllowCorrection	Required	"True"," False"	Covered in Advanced Form Integration API Technical Specification Document.
PredefinedCorrections	Conditionally Required	null	Covered in Advanced Form Integration API Technical Specification Document.
ShowIsResolved	Conditionally Required	"True"," False"	Setting to enable a flag within the UI to show on non-compliant answers.
Configuration	Required	Null	Functionality not in use, must be set to null.
IsCompliant	Conditionally Required	null	Covered in Form Compliance API Integration Technical Specification Document.
DefaultCompliance	Conditionally Required	null	Covered in Form Compliance API Integration Technical Specification Document.
StepperTypeID	Conditionally Required	ID : StepperType • ebc1926c-17ad-4c96-bfd4-a1c0f4bb404b : Numeric • b476a878-10b7-45df-ad25-9272f19a0074 : Standard • 4f21287f-19cc-4399-a1fd-2544fa1f5ef9 : Tally Optimized	Used only on Numeric fields.
StepperTypeName	Conditionally Required	"Numeric", "Standard", "Tally Optimized"	Set to Numeric for only collecting number entries, other options are for tally +/- functionality.
ElementType	Required	0	Used for internal purpose, set to zero.
IsRequired	Required	"True"," False"	Flag to indicate if field is required to be completed by user before submission.
AllowComments	Conditionally Required	"True"," False"	Optional flag to allow user to enter additional comments. Default is False.
Comment	Conditionally Required	null	Value will be entered by user, always set to null. Must include if AllowComments is set to true.
AllowAttachments	Conditionally Required	"True"," False"	Flag to allow user to attach pictures or files to the field. Default is false.
Attachments	Conditionally Required	null	Value will be entered by user, always set to null. Must include if AllowAttchments is set to true.
ShowOnCOA	Optional	"True"," False"	Flag that can be used for your own purposes for flagging data.
ShowHint	Conditionally Required	"True"," False"	Flag to reveal additional instructions or reminders to the User for that specific field. Default is False.
Hint	Optional	"Sample text value"	Include text only if ShowHint is set to True.
Repeat	Conditionally Required		Only available with numeric fields.
GroupID	Required	"00000000-0000-0000-0000-000000000000"	Suggested default GUID provided in Options column.
ShowField	Required	"True"," False"	Dictate per Resource if the field should be visible to the Resource.
FieldBankID	Optional	"00000000-0000-0000-0000-000000000000"	Suggested default GUID provided in Options column. Functionality not in use.
ParentID	Required	null	While designing form, value will always be null.
Value	Required	null	While designing form, value will always be null.
Default	Conditionally Required		Only include a value when selection should be predetermined for user, otherwise set to null.
ID	Required	"00000000-0000-0000-0000-000000000000"	Suggested default GUID provided in Options column.
Name	Required		UI Name of field that will be visible to the user
Shortname	Required		Internal UI Name that will be used in other parts of form building or API calls. Must be unique.
ShowPointsPossible	Conditionally Required	null	Must be set to null on type Check Form.
ShowPointsEarned	Conditionally Required	null	Must be set to null on type Check Form.
QuestionWeight	Conditionally Required	null	Must be set to null on type Check Form.

Field Information Parameters – Audit Form Type

Name	Required	Value Options	Description
ShowPointsPossible	Required	"True"," False"	Show or hide the points possible that can be earned to the user
ShowPointsEarned	Required	"True"," False"	Show or hide the points earned to the user.
QuestionWeight	Required	Integer value	The overall points allowed for a question, must be whole numbers no decimals.

Check Form Type Request JSON

{
  "Operation": "Insert",
  "PartialSuccess": "false",
  "RequestNo": "Request Example 01",
  "Data": [
        {
            "FormId": "",
            "FormName": "Micro-Environmental Sanitation Check",
            "Type": 0,
            "Version": "0.1",
            "Resources": [
                {
                    "Id": "",
                    "Name": "Equipment > E1 > Metal Detector Line"
                }
            ],
            "Fields": [
                {
                    "Type": 9,
                    "ShowMinMax": true,
                    "ShowTarget": false,
                    "IsIntegrated": false,
                    "DependencyRule": null,
                    "ExpressionRule": null,
                    "FailsForm": true,
                    "AllowCorrection": false,
                    "PredefinedCorrections": null,
                    "ShowIsResolved": false,
                    "Configuration": null,
                    "IsCompliant": null,
                    "DefaultCompliance": null,
                    "StepperTypeId": "ebc1926c-17ad-4c96-bfd4-a1c0f4bb404b",
                    "StepperTypeName": "Numeric",
                    "ElementType": 0,
                    "IsRequired": true,
                    "AllowComments": false,
                    "Comment": null,
                    "AllowAttachments": false,
                    "Attachments": null,
                    "ShowOnCOA": true,
                    "ShowHint": false,
                    "Hint": null,
                    "ShowPointsPossible": null,
                    "ShowPointsEarned": null,
                    "QuestionWeight": null,
                    "Order": 0,
                    "Repeat": null,
                    "GroupID": "00000000-0000-0000-0000-000000000000",
                    "ShowField": true,
                    "FieldBankId": "00000000-0000-0000-0000-000000000000",
                    "ParentId": null,
                    "Value": null,
                    "Default": null,
                    "Id": "00000000-0000-0000-0000-000000000000",
                    "Name": "ATP Reading",
                    "ShortName": "ATP Reading"
                },
                {
                    "Type": 8,
                    "ControlType": 0,
                    "Options": [
                        {
                            "Value": null,
                            "Id": "00000000-0000-0000-0000-000000000000",
                            "Name": "Metal Detector"
                        },
                        {
                            "Value": null,
                            "Id": "00000000-0000-0000-0000-000000000000",
                            "Name": "Conveyor Belt"
                        },
                        {
                            "Value": null,
                            "Id": "00000000-0000-0000-0000-000000000000",
                            "Name": "Conveyor Belt Buckets"
                        }
                    ],
                    "DependencyRule": null,
                    "ExpressionRule": null,
                    "FailsForm": true,
                    "AllowCorrection": false,
                    "PredefinedCorrections": null,
                    "ShowIsResolved": false,
                    "Configuration": null,
                    "IsCompliant": null,
                    "DefaultCompliance": null,
                    "ElementType": 0,
                    "IsRequired": true,
                    "AllowComments": false,
                    "Comment": null,
                    "AllowAttachments": false,
                    "Attachments": null,
                    "ShowOnCOA": true,
                    "ShowHint": false,
                    "Hint": null,
                    "ShowPointsPossible": false,
                    "ShowPointsEarned": false,
                    "QuestionWeight": 0,
                    "Order": 0,
                    "Repeat": null,
                    "GroupID": "00000000-0000-0000-0000-000000000000",
                    "ShowField": true,
                    "FieldBankId": "00000000-0000-0000-0000-000000000000",
                    "ParentId": null,
                    "Value": null,
                    "Default": null,
                    "Id": "00000000-0000-0000-0000-000000000000",
                    "Name": "Surfaces Swabbed",
                    "ShortName": "Surfaces Swabbed"
                }
            ]
        }
    ]
}

Response Parameters

Name	Description
RequestID	Use this GUID within our GetBatchStatus API to request updates on when the request will be processed outside of the UI. See Request Status API documentation for more information on GetBatchStatus.
RequestStatus	If no syntax errors are present the default response is Pending until the request can be processed.
RequestError	Error object providing information if an error occurs
Status	Indicating the success of the API request

Response JSON

{
    "RequestId": "774c16bd-2e03-4f8a-97ab-004cb940b800",
    "RequestStatus": "Inprocess",
    "RequestError": [
        {
            "ErrorCode": 0,
            "FieldName": null,
            "FieldValues": null,
            "ErrorMessage": "",
            "Header": null
        }
    ],
    "Status": true,
    "Errors": null,
    "RefreshToken": false
}