Templates

You should have the API key when retrieving or updating your data. Without these API keys, you cannot access your templates. Objects in API responses can gain new keys over time. Ignore any key you don't recognize.

Template Object

Top Level

{
  "id": "5fda16a7-c870-4440-a1ef-1c560c6b65bd",
  "name": "Real Estate Property Inspection",
  "template_id": "RealEstate_001",
  "description": "Renters can use this template to inspect the property and collect data on the status of the property.",
  "created_at": "2023-04-05T20:41:42.8660000Z",
  "created_by": {},
  "updated_at": "2023-04-05T20:41:42.8660000Z",
  "updated_by": {},
  "team": {},
  "data": {}
}

Field	Type	Description
`id`	string	The unique identifier (GUID) of the template
`name`	string	The name of the template
`template_id`	string	The template identifier (unique text identifier, max 20 characters)
`description`	string	Additional information or details about the template.
`created_at`	string	ISO 8601 formatted date-time when the template was created
`created_by`	object	User object who created the template (see User Object here)
`updated_at`	string	ISO 8601 formatted date-time when the template was last updated
`updated_by`	object	User object who last updated the template (see User Object here)
`team`	object	Team object associated with the template (see Team Object here)
`data`	object	Template data structure with controls (only included when `includes` parameter contains `"data"` or `"all"`)

Template data object

{
  "control_count": 6,
  "controls": [{}]
}

Key	Type	Description
`control_count`	Number	The count of controls present in the template.
`controls`	Array	An array of control object(s) representing individual control within the template.

Control object

{
  "id": "54a5a217-c261-48f5-8c40-8e85631d28b3",
  "field_id": "NameRepoter_txt",
  "type": "text",
  "path": "This is page 1/Section 1/",
  "label": "Name of reporter?",
  "children_count": 0,
  "children": [],
  "parent_id": "a7544213-c293-4db3-96e8-3c9b5c946e0c",
  "options": {}
}

Field	Type	Description
`id`	Guid	The unique identifier (GUID) of the control
`field_id`	string	The field identifier (unique text identifier)
`type`	string	The type of control. One of: `page`, `section`, `text`, `number`, `radio`, `checkbox`, `dropdown`, `date`, `media`, `signature`, `barcode`, `checkin`, `instacount`, `instructions`, `image`, `calculated_field`, `scoring_summary`.
`path`	string	The hierarchical path of the control, built from labels separated by `/`. A page's path is its label (`Page 1`), a section's path is `Page 1/Section 1`, and a control's path is its parent's path plus its label (`Page 1/Section 1/Inspector Name`, or `Page 1/Inspector Name` for a control placed directly on a page). Earlier versions returned `null` for sections, and a page or a control placed before a section could carry that section's path.
`label`	string	The display label for the control
`children_count`	integer	The count of child controls nested within these controls
`children`	array	An array of control identifiers(GUIDs) representing individual child controls nested within this control.
`parent_id`	string	The identifier of the parent control if this control is nested within another control (nullable for root-level controls)
`options`	object	Control-specific options (structure varies by control type). Refer to control options section below.

Control options

The control options object will include only fields relevant to the specific type of control. Below are all the possible options.

Key	Type	Description
placeholder	String	A placeholder text that provides a hint or example of the expected input.
is_required	Boolean	A boolean value indicating whether the control is required.
show_media	Boolean	A boolean value indicating whether media attachments can be added to the control.
show_notes	Boolean	A boolean value indicating whether additional notes or comments can be added to the control.
allow_upload_photos	Boolean	A boolean value indicating whether users can upload photos or images as part of the control.
is_multiline	Boolean	This option is exclusively available for `text` control. It indicates whether the control allows multiple lines of text.
data_view	String	This option is exclusively available for the `section` control. It determines how the associated data should be displayed in the inspection report.
is_repeatable	Boolean	This option is exclusively available for the `section` control. It indicates whether the control can be repeated or duplicated.
choices	Array	Deprecated ⚠️: use `choice_items`. `choices` will be retired in a future version. An array of the option texts of a `radio`, `checkbox` or `dropdown` control.
description	String	This option is exclusively available for `instructions` controls. It contains the instruction text written in the template builder, as plain text: line breaks are `\n`, and characters such as `&` and `<` are returned as they are.
show_time	Boolean	This option is exclusively available for `date` controls. It indicates whether time selection is enabled for the control.
choices_type	String	This option is exclusively available for `radio`, `checkbox` and `dropdown` controls. Where the options come from: `manual` (entered in the template builder), `presets` (from a preset list) or `custom_sets` (from a custom set). New values may be added; ignore values you don't recognize. `null` If the source isn't recorded.
data_source_id	String	This option is exclusively available for `radio`, `checkbox` and `dropdown` controls. For a `custom_sets` control, the id of the custom set; get its items with Get a custom set by id. `null` for other controls.
choice_items	Array	This option is exclusively available for `radio`, `checkbox` and `dropdown` controls. The control's options as choice item objects, in template order. Empty for `custom_sets` controls: read the items from the custom set in `data_source_id`.
show_in_report	Boolean	Whether the control is shown in the VLX inspection report (the template builder's "Show in VLX report" setting). `true` when the setting was never changed. Not returned for `page` and `section` controls.
layout	String	This option is exclusively available for `image` controls. How the images are arranged: `stack` or `grid`.
image_size	String	This option is exclusively available for `image` controls. Display size of the images: `large`, `medium` or `small`.
alignment	String	This option is exclusively available for `image` controls. Horizontal alignment of the images: `left`, `center` or `right`.
is_carousel	Boolean	This option is exclusively available for `image` controls. Whether the images are shown as a carousel.
columns	Integer	This option is exclusively available for `image` controls. Number of columns for the `grid` layout; `null` for the `stack` layout.
hide_label	Boolean	This option is exclusively available for `image` controls. Whether the control's label is hidden.

The images placed in an image control are not returned; only its layout settings are.

To understand the available options for a specific control type, please refer to the table below:

Control type	Available options
page	None, the option object will be empty
section	data_view and is_repeatable
text	placeholder, is_multiline, is_required, show_media, show_notes, allow_upload_photos, show_in_report
number	placeholder, is_required, show_media, show_notes, allow_upload_photos, show_in_report
radio	choices (deprecated), choices_type, data_source_id, choice_items, is_required, show_media, show_notes, allow_upload_photos, show_in_report
checkbox	choices (deprecated), choices_type, data_source_id, choice_items, is_required, show_media, show_notes, allow_upload_photos, show_in_report
dropdown	choices (deprecated), choices_type, data_source_id, choice_items, is_required, show_media, show_notes, allow_upload_photos, show_in_report
date	show_time, is_required, show_media, show_notes, allow_upload_photos, show_in_report
media	is_required, show_notes, allow_upload_photos, show_in_report
signature	placeholder, is_required, show_in_report
barcode	is_required, show_media, show_notes, allow_upload_photos, show_in_report
checkin	is_required, show_media, show_notes, allow_upload_photos, show_in_report
instacount	is_required, show_media, show_notes, allow_upload_photos, show_in_report
instructions	description, show_in_report
image	layout, image_size, alignment, is_carousel, columns, hide_label, show_in_report
calculated_field	show_in_report
scoring_summary	show_in_report

Choice item object

Each entry of choice_items is one option of a radio, checkbox or dropdown control.

{
  "id": "9a1f0c2e-3b4d-4e5f-8a6b-7c8d9e0f1a2d",
  "value": "Poor",
  "color": "#E01E53",
  "score": 0.0,
  "is_flagged": true,
  "flag": {
    "id": "5c7e2a10-8f3b-4d6a-9e21-0b4c6d8f1a3e",
    "name": "Needs repair",
    "color": "#E01E53"
  }
}

Key	Type	Description
id	String	The option's id. Inspection answers to this control return the same `id` (see Response object), so match answers to options by `id`. `null` if the option has no id.
value	String	The option's text.
color	String	The option's color (can be empty). This is not the flag's color; see `flag.color`.
score	Number	The option's score. It can be a decimal, for example `1.5`. `null` when the option has no score.
is_flagged	Boolean	Whether choosing this option flags the answer. An option can be flagged without a named flag; `flag` is then `null`.
flag	Object	The option's named flag (Flag object), or `null` when it has none. The name and color are the current ones from your organization's flag library. If the flag was deleted from the library, the name and color last saved with the option are returned.