Currently there are many different possibilities to integrate an Evalanche form into a website. All variants have specific advantages and disadvantages (see also Integrating web forms) SmartForms API (REST)
- Query form configuration:
- Submit form data
Together with a security token contained in the config, the form can then be sent back to the end point via POST request, also in JSON format. The security token is generated from various data of the GET request, so that the POST request for submitting the form can only be executed by the person who has also queried the configuration. This replaces the analogous techniques CSRF token and ReCaptcha.
The API responds to the POST request that is sent when the request is sent with a detailed response whether the entry was successful or whether errors occurred. The error codes allow a simple presentation of the validation result.
Activate Settings for Form (CORS)
Forms that are to be accessed via Form API (Rest) must have the option "Enable Form API" activated in the configuration. If the form is to be accessed from an external website, the domain of this website (origin) must also be entered in the "Allowed domains" field in the form configuration. No protocol, such as http://, must be specified here. (e.g.: sc-networks.com)
The API will only respond if both the form configuration (as described) is correct and the request has an "Origin header" that matches the configured domain.
The following example is only for understanding and testing the API and should not be used productively in this form. Individual adjustments and revisions should be made in advance.
Procedure for testing:
- Activate settings for the form (Cors), see above.
- In an Evalanche account a form must be created. In this form you can already configure arbitrary fields.
- The configuration of the form can already be tested by calling the following URL: https://INTERFACEDOMAIN/api/form/v1/FORMULAR_SID
- In the source code of the file: Form-Rest-API-JS-Prototyp.html the variable "formId" must be filled with the SID of the Evalanche form. (line 233)
- In the source code, the interface domain (without protocol) must also be defined in the variable "interfaceDomain". (line 235)
- If there should be a possibility of prefilling, the variable "profileUid" must be filled with a profile UID. (234)
Retrieving the form configuration
A form configuration is called up using a GET
The retrieved data serve the correct representation and configuration of the form and correspond to the configurations which are stored in the Evalanche object.
Unique token for validation for submitting the form data
- action: Action URL of the form
- title: Title of the form (appearance)
- shortdesc_html: Short text of the form (appearance)
- language: Language of the form (configuration)
- translation: various validation texts (appearance)
- tracking: external tracking data (configuration)
- label: Label of the field
- required: Bool, whether field is a required field
- name: Name of the field
- sort: Position of the field
- translation: various validation error texts
- hidden: Bool, whether field is visible or hidden
- readonly: Bool, whether a field may overwrite existing values or not
- default_value: Default value
- type: Field type (if necessary with a list of the possible options)
- data: Data of the specified profile
Transfer form data
The transmission of form data takes place by means of a POST
This method allows a more flexible sending via JS without having to execute the form action via Submit.
Unique token for validating the form data (see GET request)
The encrypted User-ID or null
The form data as a list of dictionaries with the field names in the form including "form_" prefix (see HTML output of the form)
- force_new_profile: Forces the creation of a new profile
- allow_empty_profile: Empty profiles are allowed
- presets: Dictionary of defaults for the presetting (same format as in "data")
Result in case of success
Result in case of error
If an error occurs during submit, a result with one of the following error codes is returned:
Since this API is a public API, measures have been taken to reduce the risk of automated mass submissions. However, these are only obstacles that make misuse very difficult - there is no absolute security.
A token is supplied with every GET request. This token contains encrypted information about the GET request and a TTL (time to live).
This token must be sent again with a following submit in order to validate the submit. As long as the TTL has not expired, the token is valid for several POST requests and behaves like a kind of "session token".
The following things are validated
- If the TTL has not yet been reached (a random value of 100-300 seconds is added to the timestamp of the GET request here)
- If the IP of the GET request is the same as that of the POST
- If the user agent of the GET request is the same as that of the POST
- Is the host used in the GET (i.e. the domain) the same as in the POST
If the validation fails, no
The following widget IDs may occur:
|4||Text input (textarea)|
|7||Dropdowns (date & time)|
|8||Text input with Trim|
|10||Display only (Readonly)|
|11||Hidden input (drop-down)|
|12||Hidden input (multiple drop-down)|
|13||Text input with large initial letters|
|16||Dropdowns (date in future)|
|17||Dropdowns (date & time in the future)|
|18||Dropdowns (with restriction of other fields)|
|19||Dropdowns (date invisible)|
|20||Dropdowns (date & time invisible)|
|22||Text input (also blank input)|
|23||Text input (single selection)|
|24||Dropdown (with zero option)|
|25||Radio buttons (with zero option)|
|27||Text input (all lower case letters)|
|28||Text input (all capital letters)|
|29||Dropdowns (date in the past)|
|30||Dropdowns (date & time in the past)|
|31||Text input (text area with blank input)|
|32||Checkboxes (only attach)|
|33||Hidden (from request)|
|34||Text input with dropdown|
|37||Dropdowns (date & time with strtotime)|
|38||Dropdowns (date with strtotime)|
|42||Circumference search with dropdown|
|43||Dropdown with groups|
The following sample code is a "Proof of Concept".
The code does notrepresent
The following form functions are currently supported by the PoC:
- Form Title
- All field types
- Order of fields in rows and columns (up to four columns)
- mandatory fields
- Default values for form fields
- Prefilled values with known profile
- Complete form validation and display of error messages from the form configuration.