Forms

Forms are ImportForm records (a GenericObject that implements IXmlMetadata). Each is bound to a parent through Object and ObjectID and defined by an ImportFormTemplate. Operations follow the standard pattern: /api/importform/{operation} runs synchronously, and /api/importform/queue/{operation} queues the operation for an app server.

Create, pause, and complete

POST /api/importform/pause?Template=Site Inspection&Object=Process&ObjectID=1042&RoofCondition=Good&InspectedOn=2026-10-05
POST /api/importform/save?ID=3301&MergeXmlData=1&Notes=No further action

Operation	Effect
save	Saves, and by default sets ActualCompletion to now if it’s empty, which completes the form. The ImportFormCompleteOnSave setting (default true) controls this.
pause	Saves without completing. Use it to create open forms from integrations.

Pass the template as Template (name) or TemplateID. The template’s Repeatable setting decides whether a save without an ID updates an existing form on the parent or inserts a new one (see Templates).

Answers (XmlData)

Any parameter that isn’t a form column, isn’t prefixed with the parent’s object name ({Object}_…), and isn’t a child-collection prefix is stored as an element under <ImportFormXml> in XmlData. Element names are made XML-safe, and invalid XML characters are stripped from values.

Caution

Without MergeXmlData, a save replaces the stored answers with the ones in the request. Pass MergeXmlData=1 when you update only some answers. Forms created from a template by workflow or CreateInstance merge by default (ImportFormMergeXmlDataDefault).

Answers are available as report fields, typed as dates for questions with the qbo-date class and as text otherwise.

Dates, workflow steps, and worklists

Field	Purpose
EstimatedStart / ProjectedStart / ActualStart	Start dates
EstimatedCompletion	Defaults to one day out (ImportFormEstimatedCompletionDays)
ProjectedCompletion	Changing it updates ProjectedOriginal (first projection) and ReprojectCount
ActualCompletion	Completes the form. On update, a date of today (no time) becomes the current time.
AssignedPersonID, AssignedCollectionID, AssignedOrganizationID	Owner, team, and company
DecisionStepID	The workflow step that created the form

On every save, a form bound to a workflow step updates that step. Setting ActualCompletion completes the step, changing it updates the step’s completion, and ProjectedCompletion is copied to the step. If the template has a worklist, the form’s work item is created, skipped, completed, or cancelled to match (see Worklists). Pass SmartWorklist={name} to place the item in a named open worklist, which QBO creates if needed.

Status changes

Set Status on save. When the template has a state diagram, a database trigger checks that the transition from the old status is listed, and that the caller has the transition’s RoleRequired or PermissionRequired. If not, the save fails with Invalid status change: …. Valid transitions complete the old status’s work items and create a new item on the transition’s worklist, unless the new status is final. transitionlist?ID=… returns the moves available from the form’s current status, with IsInRole and HasPermission flags.

Uncomplete and validate

POST /api/importform/uncomplete?ID=3301,3302&Message=Reopened: missing photos
POST /api/importform/validate?ImportFormTemplateID=12

• uncomplete clears ActualCompletion and ProjectedCompletion on the forms and their workflow steps, and removes the forms’ object links. With Message, it also logs a message on each form’s parent. Add RecipientObject and RecipientObjectID to address the message.
• validate checks the selected forms’ answers against their questions: required fields (honoring dependencies), dropdown and list values, and Validator date limits. It adds a message to each failing form, using the MessageTemplate parameter (default Task Validation Exception). It requires the ImportFormValidate permission.

Templates and questions

Operation	Purpose
/api/importformtemplate/createworklist?ID=…	Creates and binds a worklist template
/api/importformtemplate/createschema?ID=…	Generates an XSD from the questions, for imports
/api/importformtemplate/copy?ID=…	Copies a template
/api/importformtemplate/clearcache?ID=…	Clears cached views after editing
/api/importformquestion/save	Adds or updates a question: ImportFormTemplateID, ImportFormQuestion, Label, FormElement, CssClass, Behaviors, SelectOptions, DefaultValue, ValueXPath, Sequence

To set a form’s answers from a rules matrix, use /api/importform/updatefromrule (see Business Rules).

Parameters

The parameters shown are the commonly used ones. Check the method signature or statement in source (paths are listed under the page title) before relying on less common options.