The custom fields API allowes you to retrieve information about existing custom fields. You can also create new fields and update or delete existing fields.

URL

You can access the custom fields API with the followong base URL:

https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields

Retrieve information about custom fields [GET]

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields HTTP/1.1

Response:

[
  {
    "field_id": 123,
    "field_name": "field_customer_id",
    "label": "Customer ID",
    "description": "Example description",
    "type": "text_textfield",
    "field_type": "text",
    "required": false,
  },
  {
    "field_id": 156,
    "field_name": "field_confirmation",
    "label": "Cookie confirmation",
    "description": "Example description",
    "type": "checkbox_confirmation",
    "field_type": "checkbox_confirmation",
    "required": true,
  }
]

 

Retrieve information about a custom field by id [GET]

Request:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields/<field_id>

Response:

{
    "field_id": 123,
    "field_name": "field_customer_id",
    "label": "Customer ID",
    "description": "Example description",
    "type": "text_textfield",
    "field_type": "text",
    "required": false,
}

 

Retrieve information about a custom field by name [GET]

Request:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields/<field_name>

Response:

{
    "field_id": 156,
    "field_name": "field_confirmation",
    "label": "Cookie confirmation",
    "description": "Example description",
    "type": "checkbox_confirmation",
    "field_type": "checkbox_confirmation",
    "required": true,
}

 

Create custom field [POST]

Request:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields HTTP/1.1

Request body:

{
    "label": "My new textfield",
    "description": "Example description",
    "field_type": "text",
    "max_length": 128,
}

Response:

{
    "success": true,
    "field_name": "field_my_new_textfield",
    "field_id": 278,
}

 

Available options for all field types

Request Parameter	Required	Requirements	Description
field_type	Yes	string	Type of the custom field. Possible types are: "text", "selection", "date", "integer", "float", "checkbox_confirmation", "url".
label	Yes	string (32)	Visible label of the field.
description	No	string	Description of the field.
field_name	No	string (26)	This name will be used as unique identifier of the field. It can contain letters, numbers and underscores. It will automatically prefixed with "field_". If omitted, it will be generated automatically from the label.

 

Available options for specific field types

Field type: text
Description: a simple text field with up to 255 characters.

Request Parameter	Required	Requirements	Description
size	No	int min.: 2 max.: 60	The size of the text field, displayed in the contact form in the admin area. Default: 30.
max_length	No	int max.: 255	Maximum number of characters. Possible values are: 8, 16, 32, 64, 128, 255. Default is 255.

 

Field type: selection
Description: a selection of predefined values. This field type can be displayed as drop down selection, radio buttons or checkboxes.

Request Parameter	Required	Requirements	Description
field_type_option	Yes	string	Type of the selection. Possible values are: "select", "radios", "checkboxes". When this option is set to "checkboxes", the user can select multiple options. Otherwise only one option can be selected.
options	Yes	array	Key value pairs with available options. Maximum length is 255 characters per key or value. A key can contain small letters, numbers and underscores. "select" and "radios" can have up to 100 options, while "checkboxes" can only have 50 options.
default_value	No	string or array	Defines the default value, selected in the list. This must be the key of an option. In case of "checkboxes", the key(s) must be in an array. For "selection" and "radios" it must be string.

 

Field type: date
Description: field for storing dates, with or without time.

Request Parameter	Required	Requirements	Description
granularity	Yes	string	Defines if the field stores a date with or without time. Possible values are: "date_time" and "date_only".

 

Field type: integer
Description: field for storing integer numbers.

Request Parameter	Required	Requirements	Description
min	No	int	Minimum value of a number which should be stored in that field.
max	No	int	Maximum value of a number which should be stored in that field. Must be greater than 0.

 

Field type: float
Description: field for storing float numbers.

Request Parameter	Required	Requirements	Description
decimal_marker	Yes	string	The character used to separate the integer range from the decimal range. Possible values are "." and ",".
min	No	float	Minimum value of a number which should be stored in that field.
max	No	float	Maximum value of a number which should be stored in that field. Must be greater than 0.

 

Field type: checkbox_confirmation
Description: provides a checkbox for saving a contact’s confirmation. It will also display a description text with an optional link to a website with further information.

Request Parameter	Required	Requirements	Description
confirmation_text	Yes	string	This text will be shown next to the checkbox.You can use "[link]" as placeholder in the text. This placeholder will be replaced by a link, which will be built from the request parameters "link_text" and "link_url".
link_text	No	string	If present, this will be used for the visible part of the link whick replaces the placeholder "[link]" in the confirmation text.
link_url	No	string	If present, this will be used as target URL of the link which replaces the placeholder "[link]" in the confirmation text.

 

Field type: url
Description: a simple text field meant to store URLs.

This field type has no options.

 

Update custom field [PUT]

Request:

PUT https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields/<field_name> HTTP/1.1

Request body:

{
    "label": "My renamed textfield",
    "description": "Example description",
    "size": 10,
}

Response:

{
    "success": true,
    "field_name": "field_my_new_textfield",
    "field_id": 278,
}

 

Available options for all field types

Request Parameter	Required	Requirements	Description
label	No	string (32)	Visible label of the field.
description	No	string	Description of the field.

 

Available options for specific field types

Field type: text
Description: a simple text field with up to 255 characters.

Request Parameter	Required	Requirements	Description
size	No	int min.: 2 max.: 60	The size of the text field, displayed in the contact form in the admin area. Default: 30.

 

Field type: selection
Description: a selection of predefined values. This field type can be displayed as drop down selection, radio buttons or checkboxes.

Request Parameter	Required	Requirements	Description
field_type_option	No	string	Type of the selection. Possible values are: "select", "radios", "checkboxes". It is only possible to switch between "select" and "radios" (single selection), while "checkboxes" (multiple selection) cannot be changed.
options	No	array	Key value pairs with available options. Maximum length is 255 characters per key or value. A key can contain small letters, numbers and underscores. "select" and "radios" can have up to 100 options, while "checkboxes" can only have 50 options.
default_value	No	string or array	Defines the default value, selected in the list. This must be the key of an option. In case of "checkboxes", the key(s) must be in an array. For "selection" and "radios" it must be string.

 

Field type: date
Description: field for storing dates, with or without time.

This field type has no options.

 

Field type: integer
Description: field for storing integer numbers.

Request Parameter	Required	Requirements	Description
min	No	int	Minimum value of a number which should be stored in that field.
max	No	int	Maximum value of a number which should be stored in that field. Must be greater than 0.

 

Field type: float
Description: field for storing float numbers.

Request Parameter	Required	Requirements	Description
decimal_marker	No	string	The character used to separate the integer range from the decimal range. Possible values are "." and ",".
min	No	float	Minimum value of a number which should be stored in that field.
max	No	float	Maximum value of a number which should be stored in that field. Must be greater than 0.

 

Field type: checkbox_confirmation
Description: provides a checkbox for saving a contact’s confirmation. It will also display a description text with an optional link to a website with further information.

Request Parameter	Required	Requirements	Description
confirmation_text	No	string	This text will be shown next to the checkbox.You can use "[link]" as placeholder in the text. This placeholder will be replaced by a link, which will be built from the request parameters "link_text" and "link_url".
link_text	No	string	If present, this will be used for the visible part of the link whick replaces the placeholder "[link]" in the confirmation text.
link_url	No	string	If present, this will be used as target URL of the link which replaces the placeholder "[link]" in the confirmation text.

 

Field type: url
Description: a simple text field meant to store URLs.

This field type has no options.

 

Delete custom field [DELETE]

This will delete the custom field and all data its data. This cannot be undone.

Request:

DELETE https://<system_id>.<server_id>.quentn.com/public/api/V1/custom-fields/<field_name> HTTP/1.1

Response:

{
    "success": true,
    "field_name": "field_my_textfield",
}