> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/crm-automation/forms.md).
# Forms
Form is an interactive data-collection tool used to gather information directly from end users for profile updates, surveys, accepting T\&C’s and many more. You can build custom forms that automatically map answers to user profiles or store them as custom attributes, all in real-time using dedicated campaigns and powered by our segmentation engine.
### Creating & Managing Form Assets
Before displaying any form to end users via a campaign or deep link, you must first create and configure a **Form Asset**.
#### 📌 Where to Create Assets?
1. Navigate to the Marketing tab in the BO (Back Office).
2. Under the Assets subsection, select Forms and click Create to start setting up a new form template.
#### 📌 Key Asset Configurations:
* **Internal name** - Used to identify and select the asset in campaigns.
* **Status** - Can be Active, Draft, or Archived.
* **Allow direct form access** - If enabled, it allows opening this form via deep link or JavaScript API without an active campaign. It’s recommended that you keep it disabled to prevent unauthorized manual triggers. Here is how to trigger:
* **Deeplink**: dp:form\&id=123
* **JS call**: \_smartico.showForm({ id: 123 })
* **Target Segment** - select a segment of users who will be allowed to trigger the form
### Form Field configurations
You can add any number of fields which are presented as collapsible cards for easier navigation as well as options for quick reorder, clone, and delete. The setup will allow you to structure and validate the data collected from your users.
#### 1. Data Mapping
Determines how submitted user responses are stored or applied in the system:
* **Source**:
* **Property**: Connects the input directly to an existing user property (e.g., First Name, Birthdate, Language etc..).
* **Custom**: Collects data independently without updating core profile fields. The custom property and the user-submitted value are passed in the payload of the form event.
* **Property name**: (When Source = Property) Select the existing user property this form field updates upon submission.
* Let's take, for example, that you added a field connected to the user property for “first name”. When the user submits the form, the property will be overwritten with the value submitted by the user and will be automatically updated on his profile page:
* **Custom key**: (When Source = Custom) Write a custom property that is going to be exposed in the form event payload so that you can use it for mapping on your end:
* Lets take for example that you added a field with a custom key set as favorite\_game\_type. When the user submits the form the value populated for that field will be exposed in the payload:
{% hint style="info" %}
**Note**: Beware that using existing user state properties will change their value immediately on successful submission. We are not making validation of the submitted data. You can use Campaigns that trigger based on form events to insert additional steps or validation checks.
{% endhint %}
#### 2. Field Content
Defines what the user sees in the form interface and handles localization:
* **Field Title**: The headline label displayed directly above the input field on the form UI.
* **Field Type**: Select the structural input format used to capture user entries:
* **Text**: Free text input field.
* **Number**: Numeric input field.
* **Select**: Dropdown selection menu.
* **Checkbox**: Binary agreement (e.g. yes/no)
* **Date**: Calendar date selector.
{% hint style="info" %}
**Note**: Selecting an existing Smartico property automatically populates the Field Type to match that property's data type.
{% endhint %}
#### 3. Input Validation Constraints
To ensure high data quality and prevent invalid submissions, you can set specific validation constraints based on the chosen Field Type:
**Text Validation (Character Limits)**
* **min length**: The minimum number of characters required.
* **max length**: The maximum character boundary allowed.
* **pattern (regex)**: Enforces specific text formatting (e.g., requiring letters only or specific alphanumeric patterns).
**Number Validation (Value Range)**
* **min value**: The lowest acceptable numeric value.
* **max value**: The highest acceptable numeric value.
* **pattern (regex)**: Enforces specific number formatting rules (e.g, phone number, country code pattern)
What is Pattern Validation (Regex)?
While character limits control how much text someone can type and value ranges control how high or low a number can be, a Pattern (Regex) **controls the exact structure** of the data being entered.
Think of it as a **smart blueprint or template**. Instead of checking for an exact word, it checks whether the user's input matches a specific format, like checking if an email has an @ symbol or if a phone number has the right country code.
**How to Define a Regex Rule**
Regex uses special symbols as building blocks to create validation rules. You don't need to be a programmer to understand the basic pieces:
* ^ (Start): Forces the pattern to match from the beginning of the text.
* $ (End): Forces the pattern to match all the way to the end of the text.
* \[a-z] / \[A-Z]: Allows lowercase or uppercase letters.
* \[0-9] or \d: Allows digits (numbers 0 through 9).
* +: Requires one or more of the preceding character type.
* {3} or {3,10}: Sets an exact length (e.g., exactly 3 digits, or between 3 and 10 characters).
**Common Regex Patterns Cheat Sheet**
Here are the most frequently used validation patterns you can apply to text and number fields:
**1. Text & Character Formats**
| Goal / Requirement | Regex Pattern | Example Valid Inputs | Description |
| ------------------------------------ | ----------------- | ---------------------- | ------------------------------------------------------------ |
| Letters Only (No spaces/numbers) | ^\[a-zA-Z]+$ | John, Smith | Accepts uppercase and lowercase letters only. |
| Letters & Spaces (Full Names) | ^\[a-zA-Z\s]+$ | Mary Jane, De La Cruz | Accepts letters and spaces, excluding special characters. |
| Alphanumeric Only (No special chars) | ^\[a-zA-Z0-9]+$ | User123, A1B2C3 | Allows letters and numbers only. Great for IDs or usernames. |
| Alphanumeric with Spaces | ^\[a-zA-Z0-9\s]+$ | Building 4A, Suite 100 | Useful for street addresses or internal codes. |
**2. Contact & Identity Information**
| Goal / Requirement | Regex Pattern | Example Valid Inputs | Description |
| --------------------------- | ----------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
| Email Address | ^\[a-zA-Z0-9.\_%+-]+@\[a-zA-Z0-9.-]+\\.\[a-zA-Z]{2,}$ | , | Validates standard email formatting rules. |
| US Phone Number | ^\\(?\d{3}\\)?\[-.\s]?\d{3}\[-.\s]?\d{4}$ | (555) 123-4567, 555-123-4567, 5551234567 | Accepts 10-digit formats with flexible dashes/parentheses. |
| International Phone (E.164) | ^\\+\[1-9]\d{1,14}$ | +14155552671, +442071234567 | Requires a + symbol followed by country code and digits. |
| US ZIP Code | ^\d{5}(-\d{4})?$ | 90210, 90210-1234 | Accepts standard 5-digit ZIPs or 9-digit ZIP+4 formats. |
**Select Menu Items (Dropdown Options)**
When configuring a Select field type, you must add and define the dropdown choices you want to have available to the user:
* **Value**: The raw (technical) value passed in the payload upon submission.
* **Label**: The presented text label displayed to the user in the UI dropdown.
**Required field**
Located at the bottom of each field configuration setup:
* **Off**: The field is optional; users can submit the form without completing it.
* **On**: Forces the user to complete or check the field before submitting the form. If left blank, a visual error warning will prevent form submission.
### Form Content
The Form Content section gives you control over the visual presentation, structural markup, styling, and multi-language localization of the form. It features a side-by-side code editor and live visual preview, allowing you to tailor form designs to match your brand identity or gamification skin.
Note: The “Form Content” becomes available only once you save your newly created Form template.
#### What can you customize?
* **Brand Styling**: Modify CSS colors, fonts, paddings, border radii, and button states to match your brand skin.
* **Localization**: Define translations for headers, labels, placeholders, and action buttons across all supported brand languages.
* Example:
```javascript
const translations = {
"title_label": {
en: "We'd love to know you better",
pt: "", br: "", ro: "", ja: "", de: "", uk: "", fr: "",
fi: "", hy: "", au: "", el: "", ar: "", pe: "", cl: "", za: ""
}
}
```
* **HTML Layout**: Add helper text, tooltips, brand logos, or re-order visual elements.
* **Live Preview**: Test visual changes instantly in the right-hand preview panel before saving.
#### The "Regenerate" Button
If you’ve been making a lot of changes to your Form, tweaking HTML, adjusting CSS, or shifting layouts around, and realize things have gotten a bit messy, you can use the Regenerate button to start fresh. This will instantly **reset the form** back to its standard default view. However, please keep in mind that clicking Regenerate will completely overwrite all of your customized HTML and CSS (including localization), restoring everything back to the original template layout. This action is permanent and cannot be undone.
#### Edit with Vibe studio
Use **Vibe Studio** to completely customize your forms using simple, conversational prompts. Instead of manually tweaking code or navigating complex design settings, simply describe what you want in the chat, and the AI will generate and apply updates to your live preview in real time.
You can easily update visual themes and colors, automatically generate and embed custom graphics, upgrade inputs add multi-language support and so much more in seconds.
### Submissions tab
The Submissions tab allows you to view, search, and audit all individual responses gathered from end-users.
* **Overview**: View the user's details, exact submission timestamp, and total count of completed fields.
* **Expanded Details**: Click any submission row to expand it and reveal every individual field filled out during that session alongside its submitted value (e.g., phone numbers, T\&C acceptance flags, or dropdown choices).
Click the **export icon** in the upper-right corner of the table to export your filtered submission records for offline auditing or custom reporting.
### Forms in Campaign
Once a form asset is created it can be triggered within your campaigns by attaching the Form activity directly to your gamification, communications or other flow activities.
### Forms in Data Warehouse
Comprehensive form data is now available in the DWH. You can access structure, interaction, and submission data using the following views:
* [Form Definitions](https://help.smartico.ai/welcome/technical-guides/smartico-data-warehouse/smartico-dwh-crm-views#dwh_ext_xxx.dm_form): Contains the setup and structural details of your forms.
* [Form Views](https://help.smartico.ai/welcome/technical-guides/smartico-data-warehouse/smartico-dwh-crm-views#dwh_ext_xxx.frm_view): Tracks user interactions and when forms are viewed.
* [Submitted Data](https://help.smartico.ai/welcome/technical-guides/smartico-data-warehouse/smartico-dwh-crm-views#dwh_ext_xxx.frm_submit): Contains the actual data and responses submitted by users.
### Working with forms from JavaScript
**Front-End Callbacks (`_smartico.on`)**
When a form is displayed (via a campaign trigger or `_smartico.showForm(...)`, the Smartico library emits browser-side events. Subscribe to these events using `_smartico.on(...)` to react to form interactions or render submitted data in your UI.
**Subscribing to Events**
```javascript
// Fires when a form is displayed to the user
_smartico.on('form_viewed', function (data) {
// data = { id: }
console.log('Form shown:', data.id);
});
// Fires when the user successfully submits a form
_smartico.on('form_submitted', function (data) {
// data = { id: , fields: { : , ... } }
console.log('Form', data.id, 'submitted:', data.fields);
// e.g. render data.fields in your own UI
});
```
**Event Payloads**
* **Form Viewed**
* Key: `form_viewed`
* Fires: When the form is rendered.
* Payload: `{ id }` - id is the Form ID from the Back Office.
* **Form Submitted**
* Key: `form_submitted`
* Fires: After a successful submit.
* Payload: `{ id, fields }` - fields is a map of `field_key: value` pairs as configured in the Back Office.
**Targeting a Specific Form**
There is a single handler per event type. If you show multiple forms, filter by `data.id`:
```javascript
_smartico.on('form_submitted', function (data) {
if (data.id === 123) {
/* Handle form 123 submit */
}
});
```
**Unsubscribing**
Remove event listeners using `_smartico.off(...)`:
```javascript
function onSubmit(data) {
/* ... */
}
// Subscribe
_smartico.on('form_submitted', onSubmit);
// Unsubscribe
_smartico.off('form_submitted', onSubmit);
```
\
\
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.smartico.ai/welcome/products/crm-automation/forms.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.