Forms

Get one by key

Returns the full definition of one form looked up by its unique_key instead of its id, the key is trimmed and lower-cased before the lookup. A form the caller has no group access to is reported as not found rather than as forbidden.

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

Authorisation: Minimum role: USER

Request arguments

Name	Type	Source
unique_key	String

Request body example

Response

Status: 200 (OK)
Type: DTO_form

Wrapper: DTO_response_wrap

Other statuses: 400 (BadRequest), 403 (Forbidden)

Response body example

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

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_logic_operator

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

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 Aug 4, 2026 18:37