Skip to content

Order Forms API

Form Builder makes order forms: questions a client answers when ordering a product, such as a migration hostname or project notes. A product uses one form; the answers reach the order. See Custom order forms for the user guide.

Admin calls need Module access on the Formbuilder card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.

POST /api/admin/formbuilder/create_form

Creates an empty form.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
name string, required The form’s name.
type string The layout: horizontal (default) or default.
show_title string 1 to show the form’s name above it, 0 (default) to hide it.

Returns: The new form’s id.

Errors:

  • Form name was not provided (code 9999)
  • Form style was not found in predefined list (code 3657)
Example

Request parameters:

{
"name": "Website migration",
"type": "default",
"show_title": "1"
}

result:

2

POST /api/admin/formbuilder/add_field

Adds a field to a form, with a default label and name when you leave them out.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
form_id integer, required The form’s id.
type string, required text, url, select (Dropdown), radio, checkbox or textarea.
label string The question. Default: the type’s name and the field’s number, such as Text Input 3.
name string The answer’s key on the order. Default: new_<type>_<number>.
description string Help text under the field.
options object For select, radio and checkbox: an object of label to value; without it they start with three placeholder choices. For textarea: height and width (default 100 and 300). Values must be unique.
default_value mixed The pre-filled answer; an array is stored as JSON.
required integer 1 when an answer is needed.
hidden integer 1 to hide the field.
readonly integer 1 to show the default value without letting the client change it.
hide_label integer 1 to hide the label.
prefix string Text shown before the input.
suffix string Text shown after the input.
text_size integer Input size setting, kept with the field.
show_initial integer Display setting, kept with the field.
show_middle integer Display setting, kept with the field.
show_prefix integer Display setting, kept with the field.
show_suffix integer Display setting, kept with the field.

Returns: The new field’s id.

Errors:

  • Form field type is invalid (code 9999) when type is missing, (code 2684) when it is not one of the types.
  • Form id was not passed (code 9999)
  • This input type must have unique values (code 3658)
Example

Request parameters:

{
"form_id": 2,
"type": "text",
"label": "Current host",
"name": "old_host",
"required": 1
}

result:

5

POST /api/admin/formbuilder/get_form

Returns one form with its fields, in the default language.

Permission: View forms (formbuilder.view)

Parameter Type Description
id integer, required The form’s id.

Returns: The form: id, name, style (type: horizontal or default; show_title: "1" or "0"), created_at, updated_at and fields, a list by field id. Each field has id, form_id, name (the answer’s key on the order), label, hide_label, description, type, default_value, required, hidden, readonly, is_unique, options (for select, radio and checkbox: an object of label to value; for textarea: height and width), prefix, suffix, show_initial, show_middle, show_prefix, show_suffix, text_size, created_at and updated_at.

Errors:

  • Form id was not passed (code 2391)
  • Form was not found (code 9999)
Example

Request parameters:

{
"id": 2
}

result:

{
"id": 2,
"name": "Website migration",
"style": {
"type": "default",
"show_title": "1"
},
"created_at": "2026-11-02 11:00:00",
"updated_at": "2026-11-02 11:20:00",
"fields": [
{
"id": 5,
"form_id": 2,
"name": "old_host",
"label": "Current host",
"hide_label": null,
"description": "Where your website is now.",
"type": "text",
"default_value": "",
"required": 1,
"hidden": null,
"readonly": null,
"is_unique": null,
"options": [],
"prefix": null,
"suffix": null,
"show_initial": null,
"show_middle": null,
"show_prefix": null,
"show_suffix": null,
"text_size": null,
"created_at": "2026-11-02 11:05:00",
"updated_at": "2026-11-02 11:20:00"
}
]
}

POST /api/admin/formbuilder/get_form_fields

Returns the fields of a form as they are stored.

Permission: View forms (formbuilder.view)

Parameter Type Description
form_id integer, required The form’s id.

Returns: A list of fields with the keys of admin/get_form, by id. options and default_value are the stored JSON text, not decoded. An empty list for a form that does not exist.

Errors:

  • Form id was not passed (code 1822)

POST /api/admin/formbuilder/get_field

Returns one form field.

Permission: View forms (formbuilder.view)

Parameter Type Description
id integer, required The field’s id.

Returns: The field with the keys of admin/get_form. options is decoded when it holds JSON; default_value is the stored text.

Errors:

  • Field id was not passed (code 3547)
  • Field was not found (code 9999)

POST /api/admin/formbuilder/get_forms

Lists every form with how often it is used.

Permission: View forms (formbuilder.view)

No parameters.

Returns: A list (not paged). Each row has id, name, product_count and order_count.

POST /api/admin/formbuilder/delete_form

Deletes a form with its fields and their translations, and takes it off every product and order that used it.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
id integer, required The form’s id.

Returns: true.

Errors:

  • Form id was not passed (code 9958)

This cannot be undone. Answers already saved on orders stay in the orders’ settings.

POST /api/admin/formbuilder/delete_field

Deletes a form field and its translations.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
id integer, required The field’s id.

Returns: true.

Errors:

  • Field id was not passed (code 9959)
  • Field was not found (code 9999)

This cannot be undone.

POST /api/admin/formbuilder/update_field

Changes a form field. It saves every setting you send and clears the ones you leave out, so send the whole field. The choices and textarea sizes are kept when you do not send them.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
id integer, required The field’s id.
name string, required The answer’s key on the order, unique in the form. It is cleaned to lowercase letters, digits and underscores and cannot start with a digit.
label string The question. Default New field.
type string The field’s type, used only to read the choices below; the stored type does not change.
labels array For select, radio and checkbox: the choices’ labels, unique. With values, they replace the choices.
values array For select, radio and checkbox: the choices’ values, in the order of labels, unique. A choice with an empty value is dropped.
textarea_option array For textarea: the size keys, height and width. With textarea_size, they replace the sizes.
textarea_size array For textarea: the sizes in pixels, in the order of textarea_option.
options object The options as stored, used when the keys above are not sent. Left out: kept, except for a text or url field sent with type.
description string Help text under the field.
default_value mixed The pre-filled answer; an array is stored as JSON.
required integer 1 when an answer is needed.
hidden integer 1 to hide the field.
readonly integer 1 to show the default value without letting the client change it.
hide_label integer 1 to hide the label.
prefix string Text shown before the input.
suffix string Text shown after the input.
text_size integer Input size setting.
show_initial integer Display setting.
show_middle integer Display setting.
show_prefix integer Display setting.
show_suffix integer Display setting.
translations object The label and help text in other languages: an object of locale code (such as de_DE) to { "title": "...", "description": "..." }. It replaces the field’s saved translations; a language with both texts empty is dropped.

Returns: The field’s id.

Errors:

  • Field id was not passed (code 9958)
  • Field was not found (code 9999)
  • Field name cannot be empty. Please make sure it is not empty and does not contain special characters. (code 3502)
  • Field name cannot start with number. (code 1649)
  • Unfortunately field with this name exists in this form already. Form must have different field names. (code 7628)
  • This input type must have unique values (code 3658)
  • Select values must be unique (code 1597) and Select labels must be unique (code 1598), with the type’s name.
  • Textarea size options must be integer values (code 3510)
  • Invalid locale code: … (code 9999) for a language that is not installed.
Example

Request parameters:

{
"id": 6,
"name": "plan_size",
"label": "Website size",
"type": "select",
"labels": [
"Small",
"Large"
],
"values": [
"small",
"large"
],
"required": 1,
"translations": {
"de_DE": {
"title": "Größe der Website",
"description": ""
}
}
}

result:

6

POST /api/admin/formbuilder/get_pairs

Returns the forms as id and name pairs, for a drop-down list.

Permission: View forms (formbuilder.view)

No parameters.

Returns: An object of form id to form name.

Example

Request parameters:

{}

result:

{
"2": "Website migration",
"3": "Project brief"
}

POST /api/admin/formbuilder/copy_form

Makes a new form with the fields of an existing one.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
form_id integer, required The form to copy.
name string, required The new form’s name.

Returns: The new form’s id.

Errors:

  • Form id was not passed (code 9999)
  • Form name was not passed (code 9999)
  • Form was not found (code 9999)

The copy keeps the original’s layout, its fields’ choices and their texts in the installed languages.

POST /api/admin/formbuilder/update_form_settings

Renames a form and sets its layout.

Permission: Manage forms (formbuilder.manage)

Parameter Type Description
form_id integer, required The form’s id.
form_name string, required The form’s name.
type string, required The layout: horizontal or default.
show_title string 1 (default) to show the form’s name above it, 0 to hide it.

Returns: true, also when no form has that id.

Errors:

  • Form id was not passed (code 9999), and the same for the name and type.
  • Field type not supported (code 3207) for another layout.

POST /api/guest/formbuilder/get

Returns a form with its fields as the order page shows it: each field’s label and help text in the page language when a translation exists.

Parameter Type Description
id integer, required The form’s id.
default_texts boolean true to get the default-language texts instead.

Returns: The form, with the fields of admin/get_form.

Errors:

  • Form id was not passed (code 9999)
  • Form was not found (code 9999)

Any visitor can read any form by id, so never put private details in a form.