The SmartForms API enables users to utilize the functionalities of Evalanche forms independently of their standard HTML rendering. At the same time, the benefits of the tight integration of form objects into processes within Evalanche are preserved.
As a result, workflows can be largely configured and managed directly via the Evalanche GUI, without the need for extensive technical customizations. This facilitates the efficient implementation and management of form-based processes.
An overview and comparison of integration options are available here.
How the API Works
The SmartForms API is designed to fully replicate the behavior of both form retrieval and form submission. Consequently, usage via the API largely mirrors the familiar behavior experienced within the standard environment.
Most settings can continue to be configured centrally via the respective form object within the Evalanche GUI. This enables consistent and efficient management without incurring additional technical overhead.
Configuration aspects pertaining to the client-side processing and display of data are exposed and controlled via the interface.
Interplay with JavaScript
During the development of the SmartForms API, particular emphasis was placed on facilitating simple integration—via JavaScript—into any website. For this reason, conventional authentication methods were dispensed with.
Instead, security tokens with limited validity periods, along with CORS headers, are utilized to secure the communication.
Fundamentals
REST (Representational State Transfer) is an architectural style for web APIs in which all content is addressed as resources via unique URLs. Access and manipulation are performed using standardized HTTP methods such as GET (retrieval), POST (creation), PUT/PATCH (updating), and DELETE (deletion).
Each request is stateless; that is, it contains all the information required for its processing. Furthermore, the client and server are clearly separated from one another. Data transmission typically takes place in the form of JSON representations, which supports a consistent, scalable, and easily understandable API structure.
The API schema is available at the following link: https://scnem.com/api/form/v2/schema
Requests / Endpoints
GET (Retrieval of Form Configuration)
The GET request is used to retrieve the configuration data for the form in use. The response also provides a new, valid security token.
Furthermore, it is possible to request the data for a specific profile via an optional parameter. This allows the form to be displayed in a pre-filled state.
GET https://[Versanddomain]/api/form/v2/[Formular- SID]?u=[UID des Profils, optional]-
Any sending domain configured within the customer context, as well as the login domain, can be used as the sending domain. An overview of all valid URLs is available in the Integration tab of the respective form.
- The Form SID is the scrambled Object ID of the target form. It can also be found in the form's Integration tab. The "Direct URL to this object" section contains a URL that includes the corresponding `sid` parameter.
- The profile UID is the scrambled profile ID of the data record whose information is to be displayed or used within the client. The UID can, for example, be retrieved from mailings and passed on.
{
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpcCI6IjkzLjE5Ny4xOTEuMjMxIiwiYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMC4xNTsgcnY6MTQ4LjApIEdlY2tvLzIwMTAwMTAxIEZpcmVmb3gvMTQ4LjAiLCJ0YXJnZXRfaG9zdCI6InNjbmVtMi5jb20iLCJleHAiOjE3NzQyNzE5MTh9.5SeI6vGVXmIcpeN9gKZeIUum0Oyc-e22ZAOS2NcGav8",
"captcha": {
"type": "RECAPTCHA",
"public_key": "6LfU4tkUAAAAACHsryZA8oCvgjpXZTmFr2iVwZTW"
},
"form": {
"action": "https:\/\/****.com\/art_resource.php?sid=***.***",
"title": "Newsletter-Anmeldung",
"shorttext": "",
"language": "",
"translation": {
"preface_validation": "Bitte korrigieren Sie folgende Fehler",
"duplicate_validation": "Sie sind bereits eingetragen",
"missing_validation": "Markierte Pflichtfelder nicht ausgef\u00fcllt",
"failed_validation": "Die Anmeldung ist fehlgeschlagen",
"submit": "Abschicken"
},
"tracking": {
"link": "",
"campaign": ""
},
"limit": {
"entry": {
"active": false,
"maximum_subscription_count": 0,
"redirect_url": "",
"limit_reached": false
},
"time": {
"start": {
"active": false,
"date": "1970-01-01T00:00:00+00:00",
"redirect_url": "",
"limit_reached": false
},
"end": {
"active": false,
"date": "1970-01-01T00:00:00+00:00",
"redirect_url": "",
"limit_reached": false
}
}
}
},
"fields": [
{
"label": "eMail",
"required": true,
"name": "form_EMAIL",
"pool_attribute_id": 13431,
"sort": 0,
"translation": {
"validation_error": "Keine g\u00fcltige eMail-Adresse"
},
"hidden": false,
"readonly": true,
"default_value": "",
"widget_id": 10,
"auto_display": false,
"write_protection": false,
"type": "",
"options": []
},
{
"label": "MF f\u00fcr Checkbox",
"required": false,
"name": "form_MFFUERCHECKBOX",
"pool_attribute_id": 261960,
"sort": 1,
"translation": {
"validation_error": ""
},
"hidden": false,
"readonly": false,
"default_value": [],
"widget_id": 5,
"auto_display": false,
"write_protection": false,
"type": "checkbox",
"options": [
{
"key": 381458,
"value": "eine Option"
}
]
}
],
"profile": {
"uid": "78fdf425ac9e139b0e619ba42516a649",
"data": [
{
"name": "form_EMAIL",
"pool_attribute_id": 13431,
"value": "***@sc-networks.com"
},
{
"name": "form_MFFUERCHECKBOX",
"pool_attribute_id": 261960,
"value": [
381458
]
}
]
}
}
It should be noted that, in the case of a personalized request, profile data is provided in a separate section of the response.
The mapping to the individual form fields must be performed on the client side. The Widget IDs contained in the response represent the display style selected in the form configuration for the respective form fields.
POST (Data transfer to the form)
The POST request is used to transmit data to the Evalanche form. During this process, the transmitted data is validated based on the form configuration and the security token.
In the event of an error, corresponding error codes are returned. Upon success, the stored data—including a newly generated UID, if applicable—as well as the confirmation page URL configured within the form are returned, provided that a redirection is intended.
POST https://[Versanddomain]/api/form/v2/[Formular- SID]?u=[UID des Profils, optional]
Inhalt
{
"profile_uid": "",
"data": [
{
"field_name": "form_SALUTATION",
"value": "2"
},
{
"field_name": "form_FIRSTNAME",
"value": "SCN Test"
},
{
"field_name": "form_NAME",
"value": "SCN Test"
},
{
"field_name": "form_EMAIL",
"value": "***@sc-networks.com"
},
{
"field_name": "form_COMPANY",
"value": ""
},
{
"field_name": "form_TRACKING_DISABLED",
"value": "0"
},
{
"field_name": "form_GANZEZAHL",
"value": "12"
},
{
"field_name": "form_P1404375631",
"value": [
4775
]
},
{
"field_name": "form_P1404375632",
"value": "4779"
},
{
"field_name": "form_EINZEILIGEEINGABE",
"value": ""
}
],
"options": {
"force_new_profile": false,
"allow_empty_profile": false
},
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpcCI6IjkzLjE5Ny4xOTEuMjMxIiwiYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMC4xNTsgcnY6MTQ5LjApIEdlY2tvLzIwMTAwMTAxIEZpcmVmb3gvMTQ5LjAiLCJ0YXJnZXRfaG9zdCI6InNjbmVtMi5jb20iLCJleHAiOjE3NzYxNTk1MjZ9.tQsCH_1B0sBNCKPHZqabyMNI0R-jdce9rTrPNoW2pbM",
"captcha_response": ""
}
{
"result": {
"profile": {
"uid": "***",
"data": [
{
"name": "form_SALUTATION",
"pool_attribute_id": 13428,
"value": [
2
]
},
{
"name": "form_FIRSTNAME",
"pool_attribute_id": 13429,
"value": "SCN Test"
},
{
"name": "form_NAME",
"pool_attribute_id": 13430,
"value": "SCN Test"
},
{
"name": "form_EMAIL",
"pool_attribute_id": 13431,
"value": "***@sc-networks.com"
},
{
"name": "form_COMPANY",
"pool_attribute_id": 13432,
"value": ""
},
{
"name": "form_TRACKING_DISABLED",
"pool_attribute_id": 50005,
"value": "0"
},
{
"name": "form_GANZEZAHL",
"pool_attribute_id": 250964,
"value": "333"
},
{
"name": "form_P1404375631",
"pool_attribute_id": 13456,
"value": [
4776
]
},
{
"name": "form_MEHRZEILIGEEINGABEFUERSMARTFORMS",
"pool_attribute_id": 260703,
"value": "hier Link <a href="\">klick<\>"
},
{
"name": "form_P1404375632",
"pool_attribute_id": 13457,
"value": [
4779
]
},
{
"name": "form_EINZEILIGEEINGABE",
"pool_attribute_id": 260734,
"value": "Test"
}
]
},
"redirection_url": "https:\/\/scnem2.com\/art_resource.php?sid=***,u=***"
}
}
Note!
Please note that the confirmation page (redirection_url) must be accessed client-side after submitting the SmartForm in order to trigger any downstream Evalanche processes.
Validation
The interface validates the submitted data against the configuration of the Evalanche form. In the event of an error, the corresponding information is returned in an error block within the response. This block contains a code describing the type of error, as well as several lists, each containing the internal names of the affected fields.
- validation_error_attributes: An array containing fields with type or format errors
- mandatory_error_attributes: An array containing unfilled required fields
- subscription_limit_redirection: A string containing the URL to redirect to in the event of a limit being exceeded (e.g., after reaching a maximum number of entries or a defined time interval)
Example
{
"error": {
"code": 102,
"validation_error_attributes": [
"form_EMAIL"
],
"mandatory_error_attributes": [],
"subscription_limit_redirection": null
}
}
Safety Instructions
CORS
The SmartForms API provides a CORS header in the relevant responses, which can be configured within the form object under Configuration → Allowed Domains.
This enables the cross-domain use of client applications within the browser, while simultaneously enhancing security against unauthorized access and misuse.
Token Introduction
The token contains encrypted information regarding the respective GET request, as well as a defined Time-to-Live (TTL).
The token received in the GET request must be passed during a subsequent POST submission to ensure the validation of that submission. Within its valid TTL, the token may be used for multiple POST requests, thereby functioning as a session token.
Validated Parameters
During token validation, the following criteria are checked:
- The TTL must not have expired. To determine this, a random interval of 100–300 seconds is added to the timestamp of the GET request.
- The IP address of the GET request must match that of the POST request.
- The User-Agent of the GET request must be identical to that of the POST request.
- The host (domain) used in the GET request must match that of the POST request.
If the token cannot be successfully validated, error code 107 is returned.
Protection against abusive entries
Through the use of tokens—as well as transmission mechanisms that are more advanced than those found in simple GET or POST forms—a fundamental level of protection against simple, unauthorized interface access is already ensured.
Furthermore, Version 2 of the SmartForms API introduces server-side support for CAPTCHA mechanisms for the first time.
Further information is available from the providers at:
Rate Limit
Attention!
Please note that the rate limit defined in the form configuration also applies to submissions made via the SmartForms API. Therefore, in the case of a server-side implementation of the API, it may be advisable to adjust the rate limit accordingly or, if necessary, to disable it.
Code- and ID-tables
| Code | Definition |
| 101 | No profile found (when uniqueness criterion is "Profile ID" and Profile UID is missing from the request) |
| 102 | Data validation failed (Missing required fields or invalid data) |
| 103 | Login validation failed (when Permission Type is "Login Only") |
| 104 | Profile uniqueness error (For new profiles sharing the email address of an existing profile in the pool, and the "Prevent Update" option is enabled) |
| 105 | Entry limit violation |
| 106 | Required field violation |
| 107 | Invalid request / Invalid token |
| 108 | Empty profile |
| 109 | CAPTCHA validation failed |
Unabhängig davon können weitere Fehler auftreten, die durch HTTP-Statuscodes im Bereich 4XX oder 5XX gekennzeichnet sind. Diese sind gesondert zu behandeln.
| ID | Description |
| 1 | Text Input |
| 2 | Dropdown |
| 3 | Hidden Input |
| 4 | Text Input (Textarea) |
| 5 | Checkboxes |
| 6 | Dropdowns (Date) |
| 7 | Dropdowns (Date & Time) |
| 8 | Text Input with Trim |
| 9 | Radio Buttons |
| 10 | Display Only (Read-Only) |
| 11 | Hidden Input (Dropdown) |
| 12 | Hidden Input (Multi-Select) |
| 13 | Text Input with Capitalized First Letter |
| 14 | Password Input |
| 15 | Password Generator |
| 16 | Dropdowns (Future Date) |
| 17 | Dropdowns (Future Date & Time) |
| 18 | Dropdowns (Constrained by Other Fields) |
| 19 | Dropdowns (Hidden Date) |
| 20 | Dropdowns (Hidden Date & Time) |
| 21 | Checkbox |
| 22 | Text Input (Allows Empty Input) |
| 23 | Text Input (Single Select) |
| 24 | Dropdown (with Null Option) |
| 25 | Radio Buttons (with Null Option) |
| 26 | Checkbox (Hidden) |
| 27 | Text Input (All Lowercase) |
| 28 | Text Input (All Uppercase) |
| 29 | Dropdowns (Past Date) |
| 30 | Dropdowns (Past Date & Time) |
| 31 | Text Input (Textarea, Allows Empty Input) |
| 32 | Checkboxes (Append Only) |
| 33 | Hidden (from Request) |
| 37 | Dropdowns (Date & Time via StrToTime) |
| 38 | Dropdowns (Date via StrToTime) |
| 41 | Checkbox (Inverted) |
| 42 | Radius Search with Dropdown |
| 43 | Dropdown with Groups |
| 44 | Text Input (Max. 45 Chars, Filtered) |
| 45 | Text Input (Max. 45 Chars, Filtered; Allows Empty Input) |
Tips and Tricks
Hidden Fields
Fields configured as hidden within an Evalanche form cannot be overwritten with different values via the API. These fields are ignored on the server side; consequently, the value originally defined in the form is the one used in the profile.
If fields are intended to be hidden on the client side, a visible display type should be selected instead, and the corresponding logic implemented on the client side—for instance, through appropriate field naming or labeling.
Checkbox (inverted
In the case of the inverted checkbox, the interface behaves differently than it does with Evalanche forms. The submitted input value is not inverted by the interface.
Short Text
Evalanche forms feature a free-text field labeled "Short Text" (referred to as "shorttext" within the interface). This field is not used exclusively for displaying text; it can also be utilized to store structured data—for instance, for configuration purposes. Accordingly, this data is made available to the client via the interface.