Forms

List_ only aggregates

Returns the distinct values and their counts for the form properties named in field_keys, which is what a filter input needs, and never returns form rows themselves (take is forced to 0), counting only the forms the caller has group access to. Counts respect the filter passed along, while unfiltered_count on each value shows what the count would have been without it.

GET /api/{tenant:minlength(2)}/v{version:apiVersion}/forms/aggregate

Authorisation: Minimum role: USER

Request arguments

Name	Type	Source
field_keys	String[]	Query
filter	DTO_standard_filter	Query

Request body example

Response

Status: 200 (OK)
Type: DTO_form[]

Wrapper: DTO_response_wrap_get_many

Other statuses: 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 429 (TooManyRequests)

Response body example

DTO_standard_filter

Name	Type	Description
sort_by_key	String	Sort by key
response_field_keys	String[]	Only return the fields specified
filters	String[]	Each string needs to be structured: filters=field_key:operator:value1\|value2\|value3 Only used to store filters for passing along as querystring
include_aggregations	Boolean	Include aggregations
include_imported	Boolean	Include imported
search	String	Search
sort_order	ENUM sort_order	Sort order
take	Int32	Take
page	Int32	Page

DTO_form

Name	Type	ReadOnly	Description
group_access	DTO_group_access[]		Groups that may read or edit the form, where at least one entry with EDIT permission is required
sys_tags	DTO_reference[]		Label can be used on POST/PUT to create new tags
collect_to_list	DTO_reference		Custom list that submissions are stored in, required when collect_type is LIST and rejected when collect_type is TICKET
collect_to_group	DTO_reference		Group that submitted tickets are created in, required when collect_type is TICKET and rejected when collect_type is LIST
modules	DTO_form_module[]		Ordered building blocks of the form, such as headers, information texts and fields, where the same field can only be used once per form
logics	DTO_form_logic[]		Conditional rules that show or hide fields, or forward to another field or form, depending on the answers given
language	DTO_reference		Language used for the built in texts of the externally rendered form, and it must reference one of the platform languages
created_by	DTO_reference_user	ReadOnly	Created by
last_updated_by	DTO_reference_user	ReadOnly	Last updated by
id	Int32	ReadOnly	Leave empty on input
highest_group_permission	ENUM group_permission	ReadOnly	Current users highest group permission
name	String		Display name of the form, between 2 and 30 characters
unique_key	String		Lowercase url safe key used to load the form externally, between 2 and 30 characters, unique within the workspace and built from name when left empty
privacy	ENUM privacy		PUBLIC lets the form be loaded and submitted without authentication, while PRIVATE keeps it inside the workspace
collect_type	ENUM form_collect_type		Decides whether a submission becomes a ticket (TICKET) or a row in a list (LIST)
display_type	ENUM form_display_type		Layout the client renders the form with, and it is required since the server rejects a form where display_type is left unset
submit_text	String		Label of the submit button, required on create and update
ticket_subject	String		Subject given to tickets that are created from this form, so it only applies when collect_type is TICKET
primary_color	String		Main color of the embedded form, given as six hexadecimal digits with an optional leading number sign
background_color	String		Background color of the embedded form in the same format as primary_color, and the client derives the accent tones from the two colors
ai_chat_bot_enabled	Boolean (nullable)		When true, the embedded form starts as an AI chat-bot answering from approved public FAQs. Enabling requires at least 100 approved FAQ items. Nullable so clients that omit the property on update leave the stored value unchanged.
created	DateTime	ReadOnly	Set by the server in UTC when the form is first stored
last_updated	DateTime	ReadOnly	Set by the server in UTC every time the form is changed

DTO_group_access

Name	Type	ReadOnly	Description
permission	ENUM group_permission		Permission
id	Int32		Id
label	Object	ReadOnly	Label

DTO_reference

Name	Type	ReadOnly	Description
id	Int32		The id of the reference
label	Object	ReadOnly	Name/Label from referenced object.

DTO_form_module

Name	Type	Description
module_field	DTO_form_module_field	Module field
type	ENUM form_module_type	Type
text_primary	String	Text primary
text_secondary	String	Text secondary
enabled	Boolean	Enabled

DTO_form_module_field

Name	Type	Description
id	Int32	Id
label	String	Label
required	Boolean	Required
page_value_selector	String	Auto-populate from the host page: element id (e.g. "dh_email") or CSS selector (e.g. "[name='email']") of an element on the page the form is embedded on. The embed script reads its value (input value, or text content) when the form loads and applies it according to page_value_mode. Requires the script embed (dh-form.js). Null = not auto-populated. Not supported for attachment fields.
page_value_mode	ENUM form_page_value_mode	How the field behaves when auto-populated from the host page. NONE unless page_value_selector is set.

DTO_form_logic

Name	Type	Description
triggers	DTO_form_logic_trigger[]	Triggers
action	DTO_form_logic_action	Action
logic_operator	ENUM form_logic_operator	Logic operator

DTO_form_logic_trigger

Name	Type	ReadOnly	Description
module_field	DTO_reference		Module field
field_values	DTO_reference[]		Field values

DTO_form_logic_action

Name	Type	Description
forward_to_module_field	DTO_reference	Forward to module field
forward_to_form	DTO_reference	Forward to form
hide_module_fields	DTO_reference[]	Hide module fields
show_module_fields	DTO_reference[]	Show module fields

DTO_reference_user

Name	Type	ReadOnly	Description
profile_pic	String	ReadOnly	Profile pic
email	String	ReadOnly	Email
id	Int32		Id
label	Object	ReadOnly	Label

ENUM group_permission

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	READ	Read only
2	EDIT	Edit
3	FULL	Full

ENUM form_module_type

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	HEADER	HEADER
2	INFORMATION	INFORMATION
3	FIELD	FIELD
4	LINE_SEPARATOR	LINE_SEPARATOR
5	PAGE_SEPARATOR	PAGE_SEPARATOR
6	SUBMIT_MESSAGE	SUBMIT_MESSAGE

ENUM form_page_value_mode

How a form field behaves when its value is auto-populated from the host page the form is embedded on (see DTO_form_module_field.page_value_selector).

Value	Name	Description
0	NONE	Not auto-populated (default)
1	PREFILL	The field is shown, pre-filled with the value found on the page (the visitor can change it)
2	HIDE_IF_FOUND	The field is hidden when a value is found on the page (the value is submitted silently); shown as usual otherwise
3	ALWAYS_HIDDEN	The field is never shown: the value is submitted when found on the page and left empty otherwise. Required fields are still shown when nothing is found.

ENUM form_logic_operator

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	AND	AND
2	OR	OR

ENUM sort_order

Value	Name	Description
0	ASC	ASC
1	DESC	DESC

ENUM privacy

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	PRIVATE	PRIVATE
2	PUBLIC	PUBLIC

ENUM form_collect_type

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	TICKET	TICKET
2	LIST	LIST

ENUM form_display_type

Value	Name	Description
0	UNKNOWN	UNKNOWN
1	CLASSIC	CLASSIC
2	CARD	CARD

Generated Sep 18, 2026 09:31