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.
Admin calls
Section titled “Admin calls”create_form
Section titled “create_form”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:
2add_field
Section titled “add_field”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
typeis 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:
5get_form
Section titled “get_form”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" } ]}get_form_fields
Section titled “get_form_fields”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)
get_field
Section titled “get_field”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)
get_forms
Section titled “get_forms”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.
delete_form
Section titled “delete_form”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.
delete_field
Section titled “delete_field”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.
update_field
Section titled “update_field”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:
6get_pairs
Section titled “get_pairs”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"}copy_form
Section titled “copy_form”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.
update_form_settings
Section titled “update_form_settings”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.
Guest calls
Section titled “Guest calls”get (guest)
Section titled “get (guest)”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.

