SmartForms-API (REST) – Evalanche Helpcenter

Currently there are many different ways to integrate an Evalanche form into a website. All variants have specific advantages and disadvantages (see also Embedding of web forms). The new SmartForms API (REST) should create another possibility, which offers the greatest possible flexibility and is easy to use.

Here a JavaScript in the website or landing page takes over the fetching of the form configuration, the representation, validation of the data and transfer to Evalanche. The configuration can be done in Evalanche and does not have to be done on the website or landing page.

Basic procedure:

Query form configuration: A Get-Request (JSON format) can be used to query a form and field configuration via API. Subsequently, a separate JavaScript in the website takes over the display.
Submit form data: A post-request (JSON format) of the completed form data is used to submit it, which includes either a success message or an error message. Here you will find the scheme to which the incoming data must correspond. (https://scnem.com/api/form/v1/schema)

Using the API, any web page can obtain the form and field configuration of any Evalanche form as a JSON object via JavaScript using a GET request, i.e. by calling a specific URL (endpoint).

From the form and fields configuration, JavaScript can be used to generate an individual representation of the form that is customized to the web page.

Together with a security token contained in the config, the form can then be sent back to the endpoint via POST request, also in JSON format. The security token is generated from various data in the GET request, so that the POST request to send the form can only be performed by the person who also requested the configuration. This replaces the analogous CSRF token and ReCaptcha techniques.

The API responds to the POST request sent during submission with a detailed answer as to whether the entry was successful or whether errors occurred. The error codes allow for easy visualization of the validation result.

Protocol	HTTP
Style	REST
Data Coding	JSON
End point	https://DOMAIN/api/form/v1/<form-id>[/<profile-sid>]

Activate Settings for Form (CORS)

Forms that are to be accessed via Form API (Rest) must have the "Enable Form API" option 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:// may be entered here (e.g.: sc-networks.com), multiple domains must be entered separated by a comma.

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.

Example JavaScript for website or landing page

The following example is only for understanding and testing the API and should not be used productively in this form. For this purpose, individual adjustments and revisions should still be made in advance.

The following form functions are currently supported:

Form Title
All field types
Field order in rows and columns (up to four columns)
Mandatory fields
Default values for form fields
Pre-filled values for known profile
Complete form validation and display of error messages from form configuration.
Form-Limits

Example code for demonstration: SmartForm_Client.zip

Procedure for testing:

Activate settings in the form (Cors), see above.
A form must be created in an Evalanche account. In this form any fields can already be configured.
In the source code of the file: Form-API-202012.html the variable "formId" must be filled with the SID of the Evalanche form. The SID of a form can be found in the integration URL of the form behind "sid=". The SID has the following format: "xxxxx.xxxxx" e.g. "dlthr.1fkppep" (line 207)
In the source code the interface domain (without protocol) must also be specified in the variable "interfaceDomain". (line 213)
Optional: If there should be a possibility of pre-filling, the variable "profileUid" must be filled with a profile UID. (line 210)
Optional: To check the form config as JSON, it can be retrieved via a Unix console with the following command:
```
curl -H "Origin: https://INTERFACE_DOMAIN" https://INTERFACE_DOMAIN/api/form/v1/FORM_SID
```
(The INTERFACE_DOMAIN and FORM_SID variables must be replaced with your data).

Retrieving the form configuration

A form configuration is retrieved by means of a GET request, e.g. from a JavaScript within the website.

The retrieved data is used for the correct display and configuration of the form and corresponds to the configurations that are stored in the Evalanche object.

Example

token:
Unique token for validation for submitting the form data

form:
- 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)
- limit: Form-Limit (configuration)

fields:
- label: Label of the field
- required: Bool whether field is a required field
- name: Field name
- sort: Field position
- translation: various validation error texts
- hidden: Bool whether field is displayed visible or hidden becomes
- readonly: Bool whether a field may overwrite existing values or not. or not
- default_value: Default value
- type: Field type (with listing of possible options, if applicable)

profile (optional, if form is pre-filled is filled in):
- data: Data of the specified profile

Example: GET /api/form/v1/6m.38t18m/6d6b454b8ace7373ba4740d91b5c3

{
    "token": "abcdefgh1234",
    "form": {
        "action": "https:\/\/evalanche\/art_resource.php?sid=6m.38t18m",
        "title": "Newsletter subscription",
        "shortdesc_html": ">h1<Newsletter subscription>\/h1<",
        "language": "",
        "translation": {
            "preface_validation": "Please correct the following errors",
            "duplicate_validation": "You are already registered",
            "missing_validation": "Marked mandatory fields not filled in",
            "failed_validation": "The registration has failed",
            "submit": "Submit"
        },
        "tracking": {
            "link": "",
            "campaign": ""
        },
        "limit": {
            "entry": {
                "active": false,
                "max_entry": 0,
                "redirect": "",
                "limit_active": false
            },
            "time": {
                "start": {
                    "active": false,
                    "timestamp": 1598614860,
                    "redirect": "https://heise.de",
                    "limit_active": false
                },
                "end": {
                    "active": false,
                    "timestamp": 0,
                    "redirect": "",
                    "limit_active": false
                }
            }
        }
    },
    "fields": [
        {
            "label": "Salutation",
            "required": 0,
            "name": "form_SALUTATION",
            "pool_attribute_id": int,
            "sort": 0,
            "translation": {
                "validation_error": ""
            },
            "hidden": false,
            "readonly": false,
            "default_value": "",
            "widget_id": 2,
            "auto_display": false,
            "write_protection": false,
            "type": "select",
            "options": [
                {
                    "key": 0,
                    "value": "-"
                },
                {
                    "key": 1,
                    "value": "Ms."
                },
                {
                    "key": 2,
                    "value": "Mr."
                },
                {
                    "key": 3,
                    "value": "Family"
                },
                {
                    "key": 4,
                    "value": "Company"
                }
            ]
        },
        {
            "label": "First name",
            "required": 0,
            "name": "form_FIRSTNAME",
            "pool_attribute_id": int,
            "sort": 1,
            "translation": {
                "validation_error": ""
            },
            "hidden": false,
            "readonly": false,
            "default_value": "",
            "widget_id": 22,
            "auto_display": false,
            "write_protection": false,
            "type": "text",
            "options": []
        },
        {
            "label": "Name",
            "required": 0,
            "name": "form_NAME",
            "pool_attribute_id": int,
            "sort": 2,
            "translation": {
                "validation_error": ""
            },
            "hidden": false,
            "readonly": false,
            "default_value": "",
            "widget_id: 22,
            "auto_display": false,
            "write_protection": false,
            "type": "text",
            "options": []
        },
        {
            "label": "eMail",
            "required": 1,
            "name": "form_EMAIL",
            "pool_attribute_id": int,
            "sort": 3,
            "translation": {
                "validation_error": "No valid email address"
            },
            "hidden": false,
            "readonly": false,
            "default_value": "",
            "widget_id" 22,
            "auto_display": false,
            "write_protection": false,
            "type": "text",
            "options": []
        },
        {
            "label": "Company",
            "required": 0,
            "name": "form_COMPANY",
            "pool_attribute_id": int,
            "sort": 4,
            "translation": {
                "validation_error": ""
            },
            "hidden": false,
            "readonly": false,
            "default_value": "",
            "widget_id": 22,
            "auto_display": false,
            "write_protection": false,
            "type": "text",
            "options": []
        }
    ],
    "profile": {
        "uid": "6d6b454c95b8ace7373ba4740d91b5c3",
        "data": {
            "form_SALUTATION": {
                "pool_attribute_id": 649263,
                "value": [
                    2
                ]
            },
            "form_FIRSTNAME": {
                "pool_attribute_id": 649264,
                "value": "Max"
            },
            "form_NAME": {
                "pool_attribute_id": 649265,
                "value": "Mustermann"
            },
            "form_EMAIL": {
                "pool_attribute_id": 649266,
                "value": "max@mustermann.de"
            },
            "form_COMPANY": {
                "pool_attribute_id": 649267,
                "value": "Musterfirma"
            },
            "form_ADDRESS": {
                "pool_attribute_id": 649268,
                "value": "Musterstra\u00dfe"
            },
            "form_STREETNUMBER": {
                "pool_attribute_id": 649269,
                "value": "555"
            },
            "form_ZIPCODE": {
                "pool_attribute_id": 649270,
                "value": "55555"
            },
            "form_CITY": {
                "pool_attribute_id": 649271,
                "value": "Musterdorf"
            }
        }
    }
}

Transfer form data

Form data is transferred to the endpoint using a POST request.

This method allows a more flexible submit via JS without having to execute the form action via submit.

Example

token:
Unique token to validate the form data (see GET request)
profile_uid:
The encrypted user ID or zero
data:
The form data as a list of dictionaries with the field names in the form incl. "form_" prefix (cf. HTML output of the form)
options:
- force_new_profile: Forces the creation of a new profile
- allow_empty_profile: Empty profiles are allowed
- presets: Dictionary of defaults for the preassignment (same format as in "data")

Example: POST /api/form/v1/6m.38t18m

{
    "token": "abcdefgh1234",
    "profile_uid": null,
    "data": [{
        "field_name": "form_EMAIL",
        "value": "some-email@some-domain.de"
    },{
        "field_name": "form_NAME",
        "value": "Some-name"
    },{
        "field_name": "form_FIRSTNAME",
        "value": "Some-first-name"
    },{
        "field_name": "form_INTEREST",
        "value": [
          462096,
          462097
        ]
    },{
        "field_name": "form_ANSWER",
        "value": "462101"
    },{
        "field_name": "form_BOOL",
        "value": "1"
    }],
    "options": {
        "force_new_profile": false,
        "allow_empty_profile": false
    }       
}

Result in case of success

Example:

{
    "result": {
        "profile": {
            "uid": "88625be2dc052aa347fe4ecd80da1fb2",
            "data": {
                "form_SALUTATION": {
                    "pool_attribute_id": 36,
                    "value": [
                        1
                    ]
                },
                "form_FIRSTNAME": {
                    "pool_attribute_id": 37,
                    "value": "Some-first-name"
                },
                "form_NAME": {
                    "pool_attribute_id": 38,
                    "value": "Some-name"
                },
                "form_EMAIL": {
                    "pool_attribute_id": 39,
                    "value": "some-email@some-domain.de"
                },
                "form_COMPANY": {
                    "pool_attribute_id": 40,
                    "value": ""
                },
                "form_INTEREST": {
                    "pool_attribute_id": 69,
                    "value": [7, 8]
                }
            }
        },
        "redirection_url": "https://scnem.com/html/default_confirmation.html"
    }
}

Note

Please note that the confirmation page (redirection_url) must be called up by the client after submitting the smart form in order to trigger any subsequent evalanche processes.

Result in case of error

Example:

{
    "error": {
        "code": 102,
        "validation_error_attributes": [],
        "mandatory_error_attributes": [
            "form_EMAIL"
        ],
        "subscription_limit_redirection": zero
    }
}

Error codes

If an error occurs during the submit, a result is returned with one of the following of the following error codes will be returned:

101 No profile available (with uniqueness criterion "Profile-Id" and missing profile UID in the request)
102 Data validation failed (Missing mandatory fields or invalidate data)
103 Login validation failed (for Permissiontype "login only")
104 Profile uniqueness error (For new profiles with the same mail address of an already existing profile in the pool and option "Prevent update")
105 Violation of the registration limit
106 Mandatory field Injury
107 Request invalid/Token invalid
108 Profile empty

Security

As this API is a public API, measures have been taken to reduce the risk of mass have been taken to reduce the risk of automated bulk submissions. However, these are only obstacles that make misuse very difficult - there is no absolute security. use - there is no absolute security.

Token

A token is supplied with each GET request. This token contains information about the GET request and a TTL (time to live). to live).

This token must be sent again with a subsequent submit, to validate the submit. As long as the TTL has not expired, the token is valid for the token is valid for several POST requests and behaves like a kind of kind of "session token".

The following things will be validated

If the TTL has not been reached yet (a random value of 100-300 seconds is added here to the timestamp of the GET request).
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
If the host used in the GET (i.e. the domain) is the same as in the POST

If the validation fails, then no explicit error is generated. error is generated - it is then an invalid request.

Widget IDs

The following widget IDs can occur:

ID	Description
1	Text input
2	Dropdown
3	Hidden input
4	Text input (text area)
5	Checkboxes
6	Dropdowns (date)
7	Dropdowns (date & time)
8	Text input with trim
9	Radio buttons
10	Show only (Readonly)
11	Hidden input (dropdown)
12	Hidden input (multiple dropdown)
13	Text input with gr. initial letters
14	Password input
15	Password generator
16	Dropdowns (date in the future)
17	Dropdowns (date & time in the future)
18	Dropdowns (With restriction of other fields)
19	Dropdowns (date invisible)
20	Dropdowns (date & time invisible)
21	Checkbox
22	Text input (also blank input)
23	Text input (Single selection)
24	Dropdown (with zero option)
25	Radio buttons (with zero option)
26	Checkbox (invisible)
27	Text input (all lowercase)
28	Text input (all caps)
29	Dropdowns (date in past)
30	Dropdowns (date & time in past)
31	Text input (textarea with empty input)
32	Checkboxes (append only)
33	Hidden (from request)
34	Text input with dropdown
35	Object picker
36	Two dropdowns
37	Dropdowns (date & time with strtotime)
38	Dropdowns (date with strtotime)
39	Surrounding search
40	Dropdown (Mailing Frequency)
41	Checkbox (inverted)
42	Perimeter search with dropdown
43	Dropdown with groups

SmartForm_Client.zip
10 KB Download