{!sharedFeedback ? (

Was this page helpful?

{["Yes 👍", " No 👎"].map((option) => ( { const id = await handleFeedbackSubmit( option, router.asPath ); setResponseId(id); }} > {option} ))}

setFreeText(e.target.value)}
                  placeholder="Please explain why..."
                  className="focus:border-brand-dark focus:ring-brand-dark mb-2 w-full rounded-md bg-white text-sm text-slate-900 dark:bg-slate-600 dark:text-slate-200 dark:placeholder:text-slate-200"
                />
                <div className="text-right">
                  <Button
                    type="submit"
                    variant="primary"
                    onClick={(e) => {
                      e.preventDefault();
                      updateFeedback(freeText, responseId);
                      setIsOpen(false);
                      setFreeText("");
                      setSharedFeedback(true);
                    }}
                  >
                    Send
                  </Button>
                </div>
              </form>
            </PopoverContent>
          </Popover>
        </div>
      ) : (
        <div>Thanks a lot, boss! 🤝</div>
      )}
    </div>
  );
};
```

**Let’s break it down!**

Setting the local states and getting the current URL:

```tsx State Management theme={null}
const router = useRouter(); // to get the URL of the current docs page
const [isOpen, setIsOpen] = useState(false); // to close Popover after
const [sharedFeedback, setSharedFeedback] = useState(false); // to display Thank You message
const [responseId, setResponseId] = useState(null); // to store responseID (will explain more)
const [freeText, setFreeText] = useState(""); // to locally store the additional info provided by user
```

Disabling feedback if config environment variables are not set properly:

```tsx Disable feedback if incorrect config env vars theme={null}
if (
  !process.env.NEXT_PUBLIC_FORMBRICKS_COM_DOCS_FEEDBACK_SURVEY_ID ||
  !process.env.NEXT_PUBLIC_FORMBRICKS_COM_API_HOST ||
  !process.env.NEXT_PUBLIC_FORMBRICKS_COM_WORKSPACE_ID
) {
  return null;
}
```

The actual frontend (read comments):

```tsx Actual Frontend theme={null}
return (
    <div className="mt-6 inline-flex cursor-default items-center rounded-md border border-slate-200 bg-white p-4 text-slate-800 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-300">
      {!sharedFeedback ? ( // displays Feedback buttons or Thank You message
        <div>
          Was this page helpful?
          <Popover open={isOpen} onOpenChange={setIsOpen}>
            <div className="ml-4 inline-flex space-x-3">
              {["Yes 👍", " No 👎"].map((option) => ( // Popup Trigger is a button as well. This is a workaround to open the same form but send a different response to the API
                <PopoverTrigger
                  className="rounded border border-slate-200 bg-slate-50 px-4 py-2 text-slate-900 hover:bg-slate-100 hover:text-slate-600 focus:outline-none focus:ring-2 focus:ring-neutral-900 focus:ring-offset-1 dark:border-slate-700 dark:bg-slate-700 dark:text-slate-300 dark:hover:bg-slate-600 dark:hover:text-slate-300"
                  onClick={async () => {
                    const id = await handleFeedbackSubmit(option, router.asPath); // handleFeedbackSubmit sends the Yes / No choice as well as the current URL to Formbricks and returns the responseId
                    setResponseId(id); // add responseId to local state so we can use it if user decides to add more feedback in free text field
                  }}>
                  {option} // "Yes 👍" or "No 👎" - they have to be identical with the choices in the survey on app.formbricks.com for it to work (!)
                </PopoverTrigger>
              ))}
            </div>
            <PopoverContent className="border-slate-300 bg-white dark:border-slate-500 dark:bg-slate-700">
              <form> // Form to handle additional feedback by user
                <textarea
                  value={freeText}
                  onChange={(e) => setFreeText(e.target.value)}
                  placeholder="Please explain why..."
                  className="focus:border-brand-dark focus:ring-brand-dark mb-2 w-full rounded-md bg-white text-sm text-slate-900 dark:bg-slate-600 dark:text-slate-200 dark:placeholder:text-slate-200"
                />
                <div className="text-right">
                  <Button
                    type="submit"
                    variant="primary"
                    onClick={(e) => {
                      e.preventDefault(); // prevent page from reloading (default HTML behaviour)
                      updateFeedback(freeText, responseId); // update initial Yes / No response with free text feedback
                      setIsOpen(false); // close Popover
                      setFreeText(""); // remove feedback from free text field local state
                      setSharedFeedback(true); // display Thank You message
                    }}>
                    Send
                  </Button>
                </div>
              </form>
            </PopoverContent>
          </Popover>
        </div>
      ) : (
        <div>Thanks a lot, boss! 🤝</div> // Thank You message
      )}
    </div>
  );
}
```

## 3. Connecting to the Formbricks API

The last step is to hook up your new frontend to the Formbricks API. To achieve that, we followed the “[Create Response](/docs/api-reference/client-api--response/create-response)” and “[Update Response](/docs/api-reference/client-api--response/update-response)” pages in our docs.

Here is the code for the `handleFeedbackSubmit` function with comments:

```tsx handleFeedbackSubmit() function definition theme={null}
export const handleFeedbackSubmit = async (YesNo, pageUrl) => {
  const response_data = {
    data: {
      isHelpful: YesNo, // the "Yes 👍" or "No 👎" response. Remember: They have to be identical with the choices in the survey on app.formbricks.com for it to work.
      pageUrl: pageUrl, // So you know which page the user gives feedback about.
    },
  };

const payload = {
    response: response_data,
    surveyId: process.env.NEXT_PUBLIC_FORMBRICKS_COM_DOCS_FEEDBACK_SURVEY_ID, // For testing, replace this with the survey ID of your survey (more info below)
  };

try {
    const res = await fetch(
      `${process.env.NEXT_PUBLIC_FORMBRICKS_COM_API_HOST}/api/v1/client/${process.env.NEXT_PUBLIC_FORMBRICKS_COM_WORKSPACE_ID}/responses`, // For testing, replace this with the API host and workspace ID of your Development workspace on app.formbricks.com
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      }
    );

if (res.ok) {
      const responseJson = await res.json();
      return responseJson.id; // Returns the response ID
    } else {
      console.error("Error submitting form");
    }
  } catch (error) {
    console.error("Error submitting form:", error);
  }
};
```

And this is the `updateFeedback` function with comments:

```tsx updateFeedback() function definition theme={null}
export const updateFeedback = async (freeText, responseId) => {
  if (!responseId) {
    console.error("No response ID available"); // If there is not response ID, no response can be updated.
    return;
  }

const payload = {
    response: {
      data: {
        additionalInfo: freeText,
      },
      finished: true, // Lets Formbricks calculate Completion Rate
    },
  };

try {
    const res = await fetch(
      `${process.env.NEXT_PUBLIC_FORMBRICKS_COM_API_HOST}/api/v1/client/${process.env.NEXT_PUBLIC_FORMBRICKS_COM_WORKSPACE_ID}/responses/${responseId}`,
      {
        method: "PUT",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      }
    );

if (!res.ok) {
      console.error("Error updating response");
    }
  } catch (error) {
    console.error("Error updating response:", error);
  }
};
```

We're almosr there! 🤸

## 4. Setting it up for testing

Before you roll it out in production, you want to test it. To do so, you need two things:

* Workspace ID (1) of the workspace on app.formbricks.com

* Survey ID (2) of your test survey

When you are on the survey detail page, you’ll find both of them in the URL:

Now, you have to replace the IDs and the API host accordingly in your `handleFeedbackSubmit`:

```tsx Replace the ID and API accordingly theme={null}
  const payload = {
    response: response_data,
    surveyId: clgwfv4a7002el50ihyuss38x, // This is an example, replace with yours
  };

try {
    const res = await fetch(
			// Note that we also updated the API host to 'https://app.formbricks.com/'
      `https://app.formbricks.com/api/v1/client/clgwcwp4z000lpf0hur7uxbuv/responses`,
```

And lastly, in the `updateFeedback` function

```tsx Replace the ID and API here as well theme={null}
  try {
    const res = await fetch(
		// Note that we also updated the API host to 'https://app.formbricks.com/'
      `https://app.formbricks.com/api/v1/client/clgwcwp4z000lpf0hur7uxbuv/responses/${responseId}`, // Note that we also updated the API host to 'https://app.formbricks.com/'
```

### You’re good to go! 🎉

Something doesn’t work? Check your browser console for the error.

**Need help?** [Reach out in GitHub Discussions](https://github.com/formbricks/formbricks/discussions)

# Feature Chaser
Source: https://formbricks.com/docs/surveys/best-practices/feature-chaser

Learn how to harness the power of Formbricks to gather targeted user feedback on specific features. Dive deep into creating, triggering, and publishing the Feature Chaser survey to enhance your product with actionable insights for specific users.

Following up on specific features only makes sense with very targeted surveys. Formbricks is built for that.

## Purpose

Product analytics never tell you why a feature is used - and why not. Following up on specific features with highly relevant questions is a great way to gather feedback and improve your product.

## Formbricks Approach

* Trigger survey at exactly the right point in the user journey

* Never ask twice, keep your data clean

* Prevent survey fatigue with global waiting period

## Overview

To run the Feature Chaser survey in your app you want to proceed as follows:

* Create new Feature Chaser survey at [app.formbricks.com](https://app.formbricks.com/)

* Setup a user action to display survey at the right point in time

<Note>
  Formbricks Widget running? We assume that you have already installed the Formbricks Widget in your web app. It’s required to display messages and surveys in your app. If not, please follow the [Quick Start Guide (takes 15mins max.)](/docs/surveys/website-app-surveys/quickstart)
</Note>

### 1. Create new Feature Chaser

If you don't have an account yet, create one at [app.formbricks.com](https://app.formbricks.com/auth/signup)

Click on "Create Survey" and choose the template [Feature Chaser](https://formbricks.com/survey-templates/feature-chaser):

### 2. Update questions

The questions you want to ask are dependent on your feature and can be very specific. In the template, we suggest a high-level check on how easy it was for the user to achieve their goal. We also add an opportunity to provide context:

Save, and move over to where the magic happens: The “Audience” tab.

### 3. Set up a trigger for the Feature Chaser survey:

Before setting the right trigger, you need to identify a user action in your app which signals, that they have just used the feature you want to understand better. In most cases, it is clicking a specific button in your product.

You can create [Code Actions](/docs/surveys/website-app-surveys/actions#setting-up-code-actions) and [No Code Actions](/docs/surveys/website-app-surveys/actions#setting-up-no-code-actions) to follow users through your app. In this example, we will create a No Code Action.

There are two ways to track a button:

1. **Trigger by Inner Text:** You might have a button with a unique text at the end of your feature e.g. "Export Report". You can setup a user Action with the according `Inner Text` to trigger the survey, like so:

1. **Trigger by CSS Selector:** In case you have more than one button saying “Export Report” in your app and only want to display the survey when one of them is clicked, you want to be more specific. The best way to do that is to give this button the HTML `id=“export-report-featurename”` and set your user action up like so:

Please follow our [Actions manual](/docs/surveys/website-app-surveys/actions) for an in-depth description of how Actions work.

### 4. Select Action in the “When to ask” card

### 5. Last step: Set Recontact Options correctly

Lastly, scroll down to “Recontact Options”. Here you have full freedom to decide who you want to ask. Generally, you only want to ask every user once and prevent survey fatigue. It's up to you to decide if you want to ask again, when the user did not yet reply:

### 7. Congrats! You’re ready to publish your survey 💃

<Note>
  Formbricks Widget running? You need to have the Formbricks Widget installed
  to display the Feature Chaser in your app. Please follow [this tutorial (Step
  4 onwards)](/docs/surveys/website-app-surveys/quickstart) to install the widget.
</Note>

# Feedback Box
Source: https://formbricks.com/docs/surveys/best-practices/feedback-box

A step-by-step guide to creating a feedback box using Formbricks.

The Feedback Box gives your users a direct channel to share their feedback and feel heard.

## Purpose

A low friction way to gather feedback helps catching even the smallest points of frustration in user experiences. Use automations to react rapidly and make users feel heard.

## Formbricks Approach

* Make it easy: 2 clicks to share feedback

* Pipe insights where team can see them and react quickly

## Installation

To add the Feedback Box to your app, you need to perform these steps:

1. Create new Feedback Box at app.formbricks.com

2. Add user action to trigger Feedback Box

3. Update recontact settings to display correctly

### 1. Create new Feedback Box

If you don't have an account yet, create one at [app.formbricks.com](https://app.formbricks.com/auth/signup)

Then, create a new survey and look for the [Feedback Box template](https://formbricks.com/survey-templates/feedback-box):

### 2. Update question content

Change the questions and answer options according to your preference:

### 3. Create user action to trigger Feedback Box:

Go to the “Audience” tab, find the “When to send” card and choose “Add Action”. We will now use our super cool User Action Tracker:

We have two options to track the Feedback Button in your application: innerText and CSS-Selector:

1. **Inner Text:** This means that whenever a user clicks any HTML item in your app which has an `Inner Text` of `Feedback` the Feedback Box will be displayed.

2. **CSS Selector:** This means that when an element with a specific CSS-Selector like `#feedback-button` is clicked, your Feedback Box is triggered.

### 4. Select action in the “When to ask” card

### 5. Set Recontact Options correctly

Scroll down to “Recontact Options”. Here you have to choose the right settings so that the Feedback Box pops up every time the user action is performed. (Our default is that every user sees every survey only once):

### 6. You’re ready publish your survey!

## Setting up the Widget

<Note>Formbricks Widget running? You need to have the Formbricks Widget installed to display the Feedback Box in your app. Please follow [this tutorial (Step 4 onwards)](/docs/surveys/website-app-surveys/quickstart) to install the widget.</Note>

# Headless Surveys
Source: https://formbricks.com/docs/surveys/best-practices/headless-surveys

Using Formbricks as a Headless Survey Platform

This document shows how you can use Formbricks to manage survey definitions and response collection via APIs, while rendering the surveys in your own frontend and forwarding the response data to your own analytics pipelines.

## In a nutshell

### What Formbricks handles:

1. **Survey Management:** Create, update, and host survey definitions through the Formbricks Management API or dashboard.
2. **Response Handling:** Receive and securely store responses via the Client or Management API.
3. **Webhooks Delivery:** Send real-time response data to your configured endpoints when responses are created, updated, or completed.

### What you handle:

1. **Custom Survey Wrapper / UI:** Build your own front-end package that fetches the survey (via API or local cache), renders it, and captures user responses.
2. **Analysis & Reporting:** Process incoming webhook data or fetched responses in your own analytics, data warehouse, or visualization tools. You can still make use of Formbricks to view Survey stats and data, but any type of custom dashboards is currently not supported.

## Why choose this approach?

1. **Your UI, your brand:** You take full control of survey look, feel, transitions, validations, and logic in your application stack.
2. **Separation of concerns:** Formbricks functions like a specialized “Backend-as-a-Service” for survey schemas and response handling; you control the frontend and analytics.
3. **OSS, self-hostable**: With Formbricks being open source, you can self-host without vendor lock-in.

## Core components

1. **Formbricks Backend:** Use the Formbricks app or Management API to create surveys (questions, flows, locales, validations).
2. **Your UI Survey Package:** Renders your custom UI, collects the data and sends to Formbricks backend using Formbricks API. For inspiration, you can start looking [here](https://github.com/formbricks/formbricks/tree/main/packages/surveys). With an active Enterprise license you can even fork our surveys package, make changes and keep them private to your organization (freed from AGPL obligation to also release your changes under AGPL)
3. **Webhook Integration:** Using in-built Webhook integration forward the data to your Analysis tool or Data warehouse.
4. **Your Analysis Tool / Data Warehouse:** Receive all the data from Formbricks integration and process it for analysis.

## Data Flow

### **Create Survey with Formbricks:**

Create a survey in Formbricks (UI) or programmatically via the Management API. Read more about the API endpoint [here](https://formbricks.com/docs/api-reference/management-api--survey/create-survey).\
Returns: Full survey object with id, schema, and configuration.\
⚠️ Backend only: Requires API key - call from your server, not client-side.

```javascript theme={null}
POST /api/v1/management/surveys
Headers:
  x-api-key: <your-api-key>
  Content-Type: application/json

Body:
{
  "workspaceId": "your-workspace-id",
  "type": "link",
  "name": "Customer Feedback Survey",
  "questions": [
    ...
  ]
}
```

### **Fetch Survey Schema:**

Get the survey schema using the Formbricks API. Read more about the API endpoint [here](https://formbricks.com/docs/api-reference/management-api--survey/get-survey-by-id).

GET /api/v1/management/surveys/\
Headers: x-api-key: \<your-api-key>

####

**Returns**: Complete survey JSON schema including:

* Questions array with types, logic, and validation
* Display settings and styling
* Languages and translations
* Branching/skip logic
* Thank you pages and redirects

#### **Implementation Options:**

**Option A (Live)**: Your backend fetches at runtime and serves to your UI

1. Fresh data on every request
2. Requires backend proxy endpoint

⚠️ Backend only: API key required, cannot be called from browser.

**Optional:**: Store survey JSON in your CDN/storage

1. Faster client load times
2. Periodically refresh from Management API
3. Best for high-traffic scenarios

⚠️ Backend only: API key required, cannot be called from browser.

**Option B (Client Workspace API)**:  You can fetch all the survey schema and surveys from the Client side using the Client Workspace API. However, this only works for Website & App surveys since they are the only ones that are made public on the Client API for our SDK to pull into an app. Make sure that:

1. Survey type: Website & App
2. Recontact Options: Overwrite Global Waiting Time & Always show
3. Targeting: None

These are **necessary requirements** for the survey to show up in the endpoint.

More about the Endpoint [here](https://formbricks.com/docs/api-reference/client-api--environment/get-environment-state).

```javascript theme={null}
GET /api/v1/client/{workspaceId}/environment
Headers:
  Content-Type: application/json

Body:
{
  "data": {
    "actionClasses": [
      { ... },
      { ... }
    ],
    "workspace": {
      "id": "<workspace_id>",
      ...
    },
    "surveys": [
      {
        "id": "<survey_id>",
        "name": "Start from scratch",
        "status": "inProgress",
        "question": "What would you like to know?",
        "trigger": "code action",
        "ending": "Thank you! We appreciate your feedback."
      }
    ]
  }
}
```

### **Render Survey with Your Custom UI:**

Your frontend receives the survey JSON and renders it using your own UI components.

For inspiration, you can start looking [here](https://github.com/formbricks/formbricks/tree/main/packages/surveys). With an active Enterprise license you can even fork our surveys package, make changes and keep them private to your organization (freed from AGPL obligation to also release your changes under AGPL)

* Question rendering based on type (openText, multipleChoiceSingle, rating, etc.)
* Skip logic and conditional branching
* Input validation
* Progress tracking
* Custom styling and branding

### **Submit Responses to Formbricks:**

#### **Client-side Submission (Recommended):**

Post responses directly from the browser to Formbricks Client API. Read more about it [here](https://formbricks.com/docs/api-reference/client-api--response/create-response).\
✅ No authentication required - Safe for browser/mobile apps.

```javascript theme={null}
POST /api/v1/client/{workspaceId}/responses
Headers:
  Content-Type: application/json

Body:
{
  "surveyId": "survey-xyz",
  "data": {
    "question-id-1": "Customer's answer",
    "question-id-2": 5,
    "question-id-3": ["option1", "option2"]
  },
  "finished": true
}

```

#### **Server-side Submission (Alternative):**

Proxy responses through your backend.\
Use when: You need server-side validation, PII handling, or response enrichment before storage.

### **Consume Analytics & Response Data:**

#### **Option A: Real-time Webhooks (Recommended):**

Configure webhooks in Formbricks to push response data to your system. Read more about Webhooks [here](https://formbricks.com/docs/platform/features/integrations/webhooks#webhooks).

1. Go to **Settings → Workspace → Integrations → Webhooks**
2. Add your endpoint URL: [https://your-domain.com/webhooks/formbricks](https://your-domain.com/webhooks/formbricks)
3. Select triggers:
   * responseCreated - New response started
   * responseUpdated - Response in progress
   * responseFinished - Response completed

**Webhook payload example:**

```javascript theme={null}
{
  "event": "responseFinished",
  "data": {
    "id": "response-123",
    "surveyId": "survey-xyz",
    "data": {
      "question-id-1": "answer"
      ...
    },
    "createdAt": "2025-01-15T10:30:00Z",
    "finished": true
  }
}

```

Forward to your analytics tool, data warehouse, or CRM in real-time.

#### **Option B: Pull from API on Demand:**

Fetch responses periodically from your backend, read more about the Endpoint [here](https://formbricks.com/docs/api-reference/management-api--response/get-survey-responses).

```javascript theme={null}
GET /api/v1/management/responses?surveyId={surveyId}
Headers:
  x-api-key: <your-api-key>
```

# Improve Email Content
Source: https://formbricks.com/docs/surveys/best-practices/improve-email-content

Measure email content quality with Formbricks

Email remains the predominant way to communicate with your customers. Measure the effectiveness to improve your offering.

## Purpose

Measuring the content quality of both transactional and marketing emails is a key element for improving customer communication.

## Formbricks Approach

* Embed the survey into your email so it’s part of the newsletter.

* Use link prefilling to store the answer users clicked on in the email.

* Dynamic user identification to append reader's email for personalized profiles and follow ups.

## Installation

To embed the newsletter survey into your email, follow these steps:

1. Create new 'Improve Newsletter Content' survey at [app.formbricks.com](https://app.formbricks.com/)

2. Select how you where you want to display the survey.

3. Copy the embed code anywhere you want in your newsletter.

### 1. Create new 'Improve Newsletter Content' Survey

If you don't have an account yet, create one at [app.formbricks.com](https://app.formbricks.com/auth/signup)

Then, create a new survey and look for the [Improve Newsletter Content template](https://formbricks.com/survey-templates/improve-newsletter-content):

### 2. Customize Survey questions

Customize survey questions, emojis or stars however you like:

### 3. Configure Survey Settings

Navigate to the **Settings** tab and choose the type of survey you want. After that, choose **Link Survey**:

### 4. Choose how you want to embed your survey

After publishing your survey, a modal that prompts you to embed your survey will pop up.

Select the Embed Survey card and you will be directed to another modal.

### 5. Copy code to embed the survey in your newsletter

Click the button with the “View Embed Code” text at the top right corner of the modal and simply paste the HTML code for your survey anywhere you want it in your newsletter:

Send a test email to yourself and try it out 🤓

# Improve Trial Conversion
Source: https://formbricks.com/docs/surveys/best-practices/improve-trial-cr

Improve Trial Conversion with Formbricks

When a user doesn't convert, you want to know why. A micro-survey displayed at exactly the right time gives you a window into understanding the most relevant question: To pay or not to pay?

## Purpose

Understanding why free users don’t convert to paid users helps boost revenue. This insight allows you to adjust your offering to encourage more users to upgrade.

## Formbricks Approach

* Ask at exactly the right point in time.
* Ask to understand the problem, don’t ask for solutions.

## Installation

To display the Trial Conversion Survey in your app you want to proceed as follows:

* Create new Trial Conversion Survey at [app.formbricks.com](https://app.formbricks.com/).
* Set up the user action to display survey at right point in time.
* Print it.

<Note>
  ### Is the Formbricks Widget Running?

We assume you’ve already installed the Formbricks Widget in your web app, as it’s required to display messages and surveys. If not, follow the [Quick Start Guide (takes 15 mins max.)](/docs/surveys/website-app-surveys/quickstart).
</Note>

### 1. Create new Trial Conversion Survey

If you don't have an account yet, create one at [app.formbricks.com](https://app.formbricks.com/auth/signup)

Click on **Create Survey** and select the template, [Improve Trial Conversion](https://formbricks.com/survey-templates/improve-trial-conversion):

### 2. Optional: Update questions

You can update the questions and answer options.

*Want to change the button color? Adjust it in **Settings → Workspace → Appearance**!*

Save, and move over to the **Audience** tab.

### 3. Pre-segment your audience

Pre-segmentation isn't needed for this survey since you likely want to target all users who cancel their trial. You can use a specific user action, like clicking **Cancel Trial**, to show the survey only to users trying your product.

### 4. Set up a trigger for the Trial Conversion Survey:

How you trigger your survey depends on your product. There are two options:

* **Trigger by Page view:** If you have a page like `/trial-cancelled` for users who cancel their trial subscription, create a user action with the type "Page View." Select "Limit to specific pages" and apply URL filters with these settings:

Whenever a user visits this page, the survey will be displayed ✅

* **Trigger by Button Click:** In a different case, you have a “Cancel Trial" button in your app. You can setup a user Action with the `Inner Text`:

Please have a look at our complete [Actions manual](/docs/surveys/website-app-surveys/actions) if you have questions.

### 5. Select Action in the “When to ask” card

### 6. Last step: Set Recontact Options correctly

Finally, scroll down to "Recontact Options" and select the appropriate settings to gather the most insights. Ensure the survey is always displayed, even if the user has seen it in the past few days.

### 7. Congrats! You’re ready to publish your survey 🥳

<Note>
  Formbricks Widget running? You need to have the Formbricks Widget installed to display the Feedback Box in your app. Please follow [this tutorial (Step 4 onwards)](/docs/surveys/website-app-surveys/quickstart) to install the widget.
</Note>

# App Interview Prompt
Source: https://formbricks.com/docs/surveys/best-practices/interview-prompt

Maximize User Interview Participation with App Interview Prompts

The Interview Prompt allows you to pick a specific user segment (e.g. Power Users) and invite them to a user interview. Bye, bye spammy email invites, benefit from up to 6x more respondents.

## Purpose

Product analytics and app surveys are incomplete without user interviews. Set the scheduling on autopilot for a continuous stream of interviews.

## Formbricks Approach

* Pre-segment users with custom attributes. Only invite highly relevant users.

* In-app prompts (app surveys or website surveys) have a 6x higher conversion rate than email invites.

* Set scheduling user interviews on auto pilot.

* Soon: Integrate directly with your [Cal.com](http://Cal.com) account.

## Installation

To display an Interview Prompt in your app you want to proceed as follows:

1. Create new Interview Prompt at [app.formbricks.com](https://app.formbricks.com/)

2. Adjust content and settings

3. That’s it! 🎉

<Note>
  Formbricks Widget running? We assume that you have already installed the Formbricks Widget in your web app. It’s required to display messages and surveys in your app. If not, please follow the [Quick Start Guide (15mins)](/docs/surveys/website-app-surveys/quickstart)
</Note>

### 1. Create new Interview Prompt

If you don't have an account yet, create one at [app.formbricks.com](https://app.formbricks.com/auth/signup)

Click on "Create Survey" and choose the template [Interview Prompt](https://formbricks.com/survey-templates/interview-prompt):

### 2. Update prompt and CTA

Update the prompt, description and button text to match your products tonality. You can also update the button color in **Settings → Workspace → Appearance**.

In the button settings you have to make sure it is set to “External URL”. In the URL field, copy your booking link (e.g. [https://cal.com/company/user-interview).](https://cal.com/company/user-interview\).) If you don’t have a booking link yet, head over to [cal.com](http://cal.com) and get one - they have the best free plan out there!

Save, and move over to the “Audience” tab.

### 3. Pre-segment your audience

Once you clicked over to the “Audience” tab you can change the settings. In the **Who To Send** card, select “Filter audience by attribute”. This allows you to only show the prompt to a specific segment of your user base.

In our case, we want to select users who we have assigned the attribute “Power User”. To learn how to assign attributes to your users, please [follow this guide](/docs/surveys/website-app-surveys/user-identification).

Great, now only the “Power User” segment will see our Interview Prompt. But when will they see it?

### 4. Set up a trigger for the Interview Prompt:

To create the trigger to show your Interview Prompt, go to the “Audience” tab, find the “When to send” card and choose “Add Action”. We will now use our super cool User Action Tracker:

Generally, we have two types of user actions: Page views and clicks. The Interview Prompt, you’ll likely want to display it on a page visit since you already filter who sees the prompt by attributes.

1. **Page view:** Whenever a user visits a page the survey will be displayed, as long as the other conditions match. Other conditions are pre-segmentation, if this user has seen a survey in the past 2 weeks, etc.

1. **Click(Inner Text & CSS Selector):** When a user clicks an element (like a button) with a specific text content or CSS selector, the prompt will be displayed as long as the other conditions also match.

### 5. Select action in the “When to ask” card

### 6. Set Recontact Options correctly

Scroll down to “Recontact Options”. Here you have to choose the correct settings to strike the right balance between asking for user feedback and preventing survey fatigue. Your settings also depend on the size of your user base or segment. If you e.g. have thousands of “Power Users” you can easily afford to only display the prompt once. If you have a smaller user base you might want to ask twice to get a sufficient amount of bookings:

### 7. Congrats! You’re ready to publish your survey 💃 🤸

<Note>
  Formbricks Widget running? You need to have the Formbricks Widget installed to display the Feedback Box in your app. Please follow [this tutorial (Step 4 onwards)](/docs/surveys/website-app-surveys/quickstart) to install the widget.
</Note>

# Product-Market Fit
Source: https://formbricks.com/docs/surveys/best-practices/pmf-survey

How to Set Up a Product-Market Fit Survey Using Formbricks - Step-by-Step Guide

## Purpose

Measuring and understanding your PMF is crucial for building a successful business. It helps you identify what users like, what’s missing, and what to build next. This survey is ideal for measuring PMF, similar to [Superhuman](https://review.firstround.com/how-superhuman-built-an-engine-to-find-product-market-fit).

## Formbricks Approach

* Pre-segment users to only survey users who have experienced your products value.
* Never ask twice, keep your data clean.
* Run on autopilot: Set up once, keep surveying users continuously.

## Overview

To display the Product-Market Fit survey in your app you want to proceed as follows:

1. Create new Product-Market Fit survey at [app.formbricks.com](https://app.formbricks.com/)
2. Setup pre-segmentation to assure high data quality
3. Setup the user action to display survey at good point in time

<Note>
  Formbricks Widget running? You need to have the Formbricks Widget installed to display the Feedback Box in your app. Please follow [this tutorial (Step 4 onwards)](/docs/surveys/website-app-surveys/quickstart) to install the widget.
</Note>

### 1. Create new PMF survey

If you don't have an account yet, create one at [app.formbricks.com](https://app.formbricks.com/auth/signup)

Click on "Create Survey" and choose a PMF survey template. The first one is short, while the second builds on the ["Product-Market Fit Engine"](https://review.firstround.com/how-superhuman-built-an-engine-to-find-product-market-fit) developed by Superhuman.

### Optional: Update questions

You can update the questions and answer options, but based on our experience, we recommend starting with the provided template. For a detailed guide on how to use the data you're collecting, check out this [guide](https://coda.io/@rahulvohra/superhuman-product-market-fit-engine).

*Want to change the button color? You can do so in **Settings → Workspace → Appearance**!*

Save, and move over to where the magic happens: The “Audience” tab.

### 3. Pre-segment your audience

To run this survey effectively, pre-segment your user base. As mentioned earlier, asking all users can lead to misleading opinions. Focus on gathering feedback from users who have invested time in getting to know and use your product.

**Filter by attribute**: You can keep the logic to decide if a user has (or has not) experienced value in your application. This makes most sense if you want to use historic usage data to decide if a user qualifies or not. Create your logic and if it applies, send an attribute to Formbricks by e.g. `formbricks.setAttribute("Loyalty", "Experienced Value");` Here is the full manual on how to [set attributes](/docs/surveys/website-app-surveys/user-identification).

### 4. Set up a trigger for the Product-Market Fit survey:

You need a trigger to display the survey but in this case, the filtering does all the work. It’s up to you to decide to display the survey after the user viewed a specific subpage (pageURL) or after clicking an element. Have a look at the [Actions manual](/docs/surveys/website-app-surveys/actions) if you are not sure how to set them up:

### 5. Select Action in the “When to ask” card

### 6. Last step: Set Recontact Options correctly

Lastly, scroll down to “Recontact Options”. Here you have to choose the correct settings to make sure your data remains of high quality. You want to make sure that this survey is only responded to once per user. It is up to you to decide if you want to display it several times until the user responds:

### 7. Congrats! You’re ready to publish your survey 💃

<Note>
  Formbricks Widget running? You need to have the Formbricks Widget installed to display the Feedback Box in your app. Please follow [this tutorial (Step 4 onwards)](/docs/surveys/website-app-surveys/quickstart) to install the widget.
</Note>

# Quiz Time
Source: https://formbricks.com/docs/surveys/best-practices/quiz-time

How to Create a Quiz Using Formbricks - Step-by-Step Guide

# Creating a quiz with Formbricks - Step-by-step Guide

Welcome to this guide on creating engaging quizzes with Formbricks! Quizzes help you capture customer insights, explore user personalities, or simply add fun for your team. With Formbricks, you can personalize quizzes in minutes add scores, customize backgrounds, and more, all without any technical skills!

## What we'll build

By the end of this tutorial, you'll have created a simple trivia Quiz featuring:

1. Score calculations.
2. Multiple endings depending on the score.

## Setting up the form

First, make sure you have a Formbricks account. If not, you can create one [here](https://app.formbricks.com):

1. Head to the Surveys page and click on **New Survey**.
2. Select Start from Scratch to create a new form.
3. Go to the settings and select form type as **Link Survey**
4. In the form editor, click the three dots next to a question, then select Change Question Type and choose **Single-Select**.

5. Add a welcoming statement to greet your users and explain the Quiz's purpose.
6. Personalize the greeting to make it inviting and encourage engagement.

**Note:** While we’re creating a Link Survey here, the process is similar for Web and App surveys.

## Adding the questions

Next, let's create a question for example with multiple options:

What country has the longest coastline in the world?
A) Canada
B) Japan
C) India
D) Nepal

## Calculate Score

Now that we have our question ready, let’s add the logic to calculate scores.

1. Scroll down in the editor and click on variables.
2. Create a new variable named `score` with a default value of 0

3. Now go back to the question and expand the advanced settings by clicking on `> Show Advanced Settings`.
4. Under the conditional logic you should see the option to `Add Logic`. Click on that.

5. Now you should see conditional logic. Customize the logic to match your needs for example:

**When** `question` equals `YOUR_ANSWER_HERE` **Then** `Calculate` `score` `Add +` `01`. So it should look something like this.

6. Let's duplicate and customize these questions. Click on the duplicate icon at the top of the question.
7. Now edit the questions, options, and answers in the **conditional logic**

## Creating Multiple Endings Based on Scores

Once you have all the questions and the calculation logic in place, it’s time to customize the endings. Scroll down to the Ending Card section. We will create two cards for this quiz: one for when the user fails the quiz and another for when the user passes.

1. Customize the ending card.
2. Display the score by typing `@score`. ( You can address all the variables or questions by just typing @ ).
3. Add logic to the last question. ( this is necessary to redirect the user based on the score ). Kind of like this:

**When** `score` >= `03` **Then** `Jump to` `Pass`. So it should look something like this.

4. Ensure that the Fail card is positioned above the Pass card. This allows any condition that does not meet the criteria of being greater than or equal to 3 to jump to the Fail card.

5. That's it! Now you can save and publish the quiz.

# Wrapping Up

Congratulations! You’ve successfully created a Quiz with Formbricks. You can play around with the quiz that we just created [here](https://app.formbricks.com/s/cm2wwt3vu0001ir8o7ys0bezz).

A great quiz can serve as an excellent lead generator, a job fit checker, or just a fun icebreaker for your team. You now have the skills to build that! If you want to read more about building quizzes and how you can create a Job Fit Quiz check this article [here](https://www.harshbhat.me/blog/formbricks-quiz).

# Panel Management
Source: https://formbricks.com/docs/surveys/best-practices/research-panel

Build and manage your own research panel using Formbricks to collect profiling data, create targeted segments, and distribute personalized survey links to panel members.

## Purpose

A research panel is a pre-recruited group of participants who have agreed to take part in multiple surveys over time. Building your own panel enables you to:

* Conduct research with a well-understood audience
* Target specific demographics or user profiles
* Distribute surveys quickly without recruiting new participants each time
* Track participant engagement and responses over time

## Formbricks Approach

Formbricks provides all the tools you need to build and manage a research panel:

* **Profiling surveys** to collect participant demographics and preferences
* **Contact management** to store and organize panel member data
* **Segments** to group participants by attributes for targeted research
* **Personal links** to distribute unique survey links to specific panel members

## Overview

Building a research panel with Formbricks involves these key steps:

1. Create a profiling survey to collect panel member information
2. Export responses and prepare contact data
3. Upload contacts into Formbricks
4. Create segments to group panel members
5. Create research surveys and distribute personal links

## Step-by-step guide

<Steps>
  <Step title="Create a profiling survey">
    Start by creating a survey to collect essential information about your panel members. This profiling survey should gather:

* **Contact information**: Email, name, and any identifiers you need
    * **Demographics**: Age, location, occupation, etc.
    * **Preferences**: Product usage, interests, or other relevant attributes

To create your profiling survey:

1. Go to [app.formbricks.com](https://app.formbricks.com) and click **Create Survey**
    2. Choose a blank survey or start from a template
    3. Add questions to collect the data you need for segmentation
    4. Include a **Contact Info** question type to capture email addresses

<Step title="Collect profiling responses">
    Distribute your profiling survey and collect responses from potential panel members. You can share the survey via:

* Direct link
    * Email
    * Social media
    * Your website

Wait until you have collected a sufficient number of responses to build your panel.
  </Step>

<Step title="Download the responses CSV">
    Once you have collected responses, export them for processing:

1. Navigate to your profiling survey's **Summary** page
    2. Click the **Download** button
    3. Select **CSV** format
    4. Save the file to your computer

This CSV contains all the profiling data from your respondents.
  </Step>

<Step title="Download the example contact upload CSV">
    To understand the required format for uploading contacts, download the example CSV:

1. Go to the **Contacts** section in your Workspace
    2. Click **Upload Contacts**
    3. Download the **Example CSV** to see the required column structure

The example CSV shows you the format Formbricks expects for contact uploads, including required fields like email and optional attribute columns.
  </Step>

<Step title="Map profiling responses to contact attributes">
    Transform your profiling survey responses into the contact upload format:

1. Open both CSV files (responses and example template)
    2. Create a new spreadsheet matching the upload template structure
    3. Map each profiling survey question to a contact attribute column:
       * Email → `email` column
       * Name → `firstName`, `lastName` columns
       * Other answers → Custom attribute columns

Example mapping:

| Survey Question                 | Contact Attribute       |
    | ------------------------------- | ----------------------- |
    | "What is your email?"           | `email`                 |
    | "What is your name?"            | `firstName`, `lastName` |
    | "What industry do you work in?" | `industry`              |
    | "How large is your company?"    | `companySize`           |
    | "What is your job title?"       | `jobTitle`              |
  </Step>

<Step title="Upload contacts to Formbricks">
    Import your panel members into Formbricks:

1. Go to the **Contacts** section
    2. Click **Upload Contacts**
    3. Select your prepared CSV file
    4. Review the attribute mapping
    5. Complete the upload

Your panel members are now stored in Formbricks with their profiling attributes.
  </Step>

<Step title="Create segments for targeting">
    Group your panel members into segments based on their attributes:

1. Go to the **Contacts** tab

2. Click **Create Segment**

3. Define filter conditions based on the attributes you collected:

* Example: `industry` equals "Technology" AND `companySize` equals "50-200"

4. Name your segment descriptively (e.g., "Tech SMB Professionals")

5. Save the segment

Create multiple segments for different research needs. Learn more about [Attribute-based Targeting](/docs/surveys/website-app-surveys/attribute-based-targeting) for detailed segmentation options.
  </Step>

<Step title="Create a research survey">
    Now create the survey you want to distribute to your panel:

1. Click **Create Survey**
    2. Design your research survey with the questions you need
    3. Configure survey settings as needed
    4. Publish the survey
  </Step>

<Step title="Generate personal links for your segment">
    Distribute unique survey links to your panel segment:

1. Navigate to your research survey's **Summary** page
    2. Click **Share survey**
    3. Select the **Personal Links** tab
    4. Choose the segment you want to survey from the dropdown
    5. Optionally set an expiry date for the links
    6. Click **Generate & download links**

You'll receive a CSV file containing unique survey links for each panel member in the segment. Learn more about [Personal Links](/docs/surveys/link-surveys/personal-links).
  </Step>

<Step title="Distribute your survey">
    Send the personal links to your panel members using your preferred method:

* Email marketing platform
    * Direct email
    * SMS
    * Any other communication channel

Each panel member receives their unique link, and their responses will be automatically attributed to their contact record.
  </Step>
</Steps>

## Benefits of this approach

| Benefit                  | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| **Response attribution** | Know exactly who responded to each survey                |
| **Targeted research**    | Survey specific segments without bothering others        |
| **Panel management**     | Maintain a centralized database of research participants |
| **Reusability**          | Use the same panel for multiple research initiatives     |
| **Data enrichment**      | Build up participant profiles over time with each survey |

## Next steps

* [Personal Links](/docs/surveys/link-surveys/personal-links) - Learn more about generating and managing personal survey links
* [Attribute-based Targeting](/docs/surveys/website-app-surveys/attribute-based-targeting) - Explore detailed segmentation options
* [Hidden Fields](/docs/surveys/general-features/hidden-fields) - Pass additional data into surveys via URL parameters

# Understanding Formbricks Survey Types
Source: https://formbricks.com/docs/surveys/best-practices/understanding-survey-types

This guide explains the differences between Formbricks Link Surveys and Website & App Surveys to help you choose the right option.

## Quick comparison

| Feature                       | Link Surveys                                           | Website & App Surveys                                                   |
| ----------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| **Best for**                  | Known touchpoints                                      | Behavior-based intercepts                                               |
| **SDK required**              | No                                                     | Yes                                                                     |
| **Delivery**                  | Email, SMS, push, or webview                           | Triggered in-app by SDK                                                 |
| **Segmentation**              | You control externally                                 | Built-in via Formbricks                                                 |
| **Survey fatigue prevention** | You control externally                                 | Automatic                                                               |
| **User identification**       | [Personal Links](/docs/surveys/link-surveys/personal-links) | [SDK user attributes](/docs/surveys/website-app-surveys/user-identification) |

## Link Surveys

Also known as **invitation-based surveys**. No SDK needed. You control when and who receives the survey, often through CRMs, marketing tools, or similar platforms.

### Delivery channels

* Email
* SMS
* Push notification
* In-app webview

### URL features

* **[Hidden Fields](/docs/surveys/general-features/hidden-fields)**: Pass user ID, order ID, or any identifier
* **[Data prefilling](/docs/surveys/link-surveys/data-prefilling)**: Pre-populate answers and optionally skip prefilled questions
* **[Personal Links](/docs/surveys/link-surveys/personal-links)**: Generate unique survey links for individual contacts

### Webview with Embed mode

For mobile apps, you can display Link Surveys in a webview with full control over when the survey appears. Your app decides the timing—open the webview when the moment is right.

**Enable Embed mode** by appending `?embed=true` to the survey URL:

```
https://app.formbricks.com/s/<surveyId>?embed=true&userId=123
```

**Listen for events** to close the webview automatically:

```javascript theme={null}
window.addEventListener("message", (event) => {
  if (event.data === "formbricksSurveyCompleted") {
    closeWebView();
  }
});
```

This approach gives you full control:

* **When**: Your app opens the webview at the right moment (after purchase, case closed, etc.)
* **Who**: Personal links allow you to have unique links for identified contacts.
* **Display**: Survey renders inside your app
* **Dismissal**: Close the webview on completion or user exit

Learn more in the [Embed Surveys guide](/docs/surveys/link-surveys/embed-surveys).

### When to use

* You already decide externally who should receive which survey
* Survey timing is tied to a known event such as a click on a link or button and in **each case**, you want to show the survey
* You want fastest approach to production
* Your platform doesn't have a supported SDK
* You don't need Formbricks attribute-based targeting & survey fatigue controls

## Website & App Surveys (SDK)

Also known as **intercept surveys**. Requires SDK integration. Formbricks handles targeting, triggering, and survey fatigue.

### In-app features

**[Action tracking](/docs/surveys/website-app-surveys/actions)**

Track in-app events and trigger surveys based on them:

```javascript theme={null}
formbricks.track("action_name");
```

**Built-in survey cooldown**

* Global waiting time (e.g., show max 1 survey every 7 days per user)
* Per-survey overrides for high-priority surveys

**[Attribute-based Targeting](/docs/surveys/website-app-surveys/attribute-based-targeting)**

Target surveys based on user attributes (plan type, language, feature flags).

**In-app display**

Surveys appear inside your app as modals or slide-ins.

### When to use

* You want Formbricks to handle who sees which survey
* Surveys should trigger based on user behavior (page views, clicks, custom events)
* You want automatic survey fatigue prevention
* You need percentage-based sampling (e.g., show to 10% of users)

## Decision guide

<AccordionGroup>
  <Accordion title="Do you control survey triggering externally?">
    Use **Link-based Surveys**. Send the URL when the moment is right, even for in-app surveys.Pass context via Hidden Fields.
  </Accordion>

<Accordion title="Should surveys trigger based on in-app behavior?">
    Use **Website & App Surveys**. The SDK tracks actions and triggers surveys automatically.
  </Accordion>

<Accordion title="Do you want automatic survey fatigue prevention?">
    Use **Website & App Surveys**. Built-in cooldown prevents over-surveying.
  </Accordion>

<Accordion title="Need the fastest path to production?">
    Start with **Link Surveys**. No SDK integration needed. Add SDK later if you need behavior-based triggers.
  </Accordion>
</AccordionGroup>

***

**Need help?** [Join us in GitHub Discussions](https://github.com/formbricks/formbricks/discussions)

# Add Image / Video
Source: https://formbricks.com/docs/surveys/general-features/add-image-or-video-question

Enhance your questions by adding images or videos. This makes instructions clearer and the survey more engaging.

<Note>
  **Self-Hosting Requirements**: Adding images to questions requires file upload storage to be configured. If
  you're self-hosting Formbricks, make sure to [configure file
  uploads](/docs/self-hosting/configuration/file-uploads) before using this feature.
</Note>

## How to Add Images

Click the icon on the right side of the question to add an image or video:

Upload an image by clicking the upload icon or dragging the file. Images must be 5 MB or less:

## How to Add Videos

Toggle to add a video via link:

### Supported Video Platforms

We support YouTube, Vimeo, and Loom URLs.

<Note>
  **YouTube Privacy Mode**: This option reduces tracking by converting YouTube URLs to no-cookie URLs. It only
  works with YouTube.
</Note>

# Conditional Logic
Source: https://formbricks.com/docs/surveys/general-features/conditional-logic

Create complex survey logic with the Logic Editor. Use conditions, actions, and variables to create a personalized survey experience.

## Terminology

* **Condition**: A rule that determines when an action should be executed.

* **Action**: A task that is executed when a condition is met.

## **Creating Logic**

* **Add a Logic Block**: Click the `Add logic +` button to add a new logic block.

<Note>
  You can add multiple logic blocks to a survey. Logic blocks are executed in
  the order they are added. You can rearrange the order of logic blocks.
</Note>

* **Add Conditions**: Add conditions to the logic block. Conditions are rules that determine when an action should be executed.

Conditons can be based on:

* **Question**: The answer to a question.

* **Variable**: A variable value.

* **Hidden Field**: The value of a hidden field.2.a **Condition Options**: Choose from a list of available conditions.

* **Condition Operators**: Choose an operator to compare the condition value.

* **Condition Value**: Enter a value to compare the condition against.
  Comparisons can be made against a fixed value or a dynamic value.
  Dynamic values can be based on a question, variable, or hidden field.

<Note>
  Conditions can be grouped. Conditions can be combined using AND or OR
  operators. You can add multiple conditions to a logic block. Conditions are
  evaluated in the order they are added.
</Note>

* **Add Actions**: Add actions to the logic block. Actions are tasks that are executed when a condition is met.

<Note>
  You can add multiple actions to a logic block. Actions are executed in the
  order they are added.
</Note>

* **Action Options**: Choose from a list of available actions.

Action is of the following types:

* **Calculate**: Perform a calculation. These variables are then available for use in other questions.

* Calculations can be performed on variables.

* Calculations can be based on fixed values or dynamic values.

* **Require Answer**: Make a question required. Only the optional questions can be marked as required while filling the survey.

* **Jump to Block**: Skip to a specific block. The user will be redirected to the specified block based on the condition.

* **Save Logic**: Click the `Save` button to save the logic block.

## Block Logic

This logic is executed when the user reaches the block. Logic can be as simple as showing a follow-up block based on earlier answers or as complex as calculating a score based on multiple answers.

# Email Follow-ups
Source: https://formbricks.com/docs/surveys/general-features/email-followups

Automatically send customized emails to respondents based on their survey responses or specific survey endings.

<Warning>
  Email Follow-ups are being deprecated in favor of [Workflows](/docs/workflows/overview). Workflows
  offer the same response- and ending-based email automation plus additional triggers and actions. We recommend
  building new email automations as Workflows.
</Warning>

<Note>
  Email followups is a paid feature. It is only available for users on paid plans or if you have [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

## What are Email Follow-ups?

Email followups allow you to automatically send customized emails to respondents based on their survey responses or when they reach specific survey endings. This feature is perfect for:

* Sending thank you notes
* Following up with respondents
* Providing additional information
* Sharing survey response data

### Trigger Types

<Card title="Response-based">
  Emails are sent when a response to your survey is completed.
</Card>

<Card title="Ending-based">
  Emails are triggered when respondents reach specific survey endings.
</Card>

## Setting Up Email Follow-ups

<Steps>
  <Step title="Go to Follow-ups Section and Create New Follow-up">
    Navigate to the survey editor and access the Follow-ups section.
  </Step>

<Step title="Configure Recipients">
    The "To" field can be configured to use:

<ul>
      <li><strong>Verified Email:</strong> The email address entered in the email verification step (when email verification is enabled)</li>
      <li><strong>Email Questions:</strong> Responses to question type `Open Text` of type `email`</li>
      <li><strong>Contact Info:</strong> Responses to question type `Contact`</li>
      <li><strong>Hidden Fields:</strong> Values from hidden fields</li>
      <li><strong>Team Members:</strong> Members of your team</li>
      <li><strong>Yourself:</strong> Your own email address</li>
    </ul>

<Step title="Set Up Reply-To">
    * Add one or more valid email addresses
    * Addresses can be added by typing and pressing space or comma
    * Invalid email addresses are automatically rejected
  </Step>

<ul>
      <li><strong>Subject:</strong> Customize your email subject line</li>
      <li><strong>Body:</strong> Supports basic HTML formatting (`p`, `span`, `b`, `strong`, `i`, `em`, `a`, `br` tags)</li>

<li>
        <strong>Survey Response Data:</strong> Option to include detailed response data with support for:

<ul>
          <li>File uploads</li>
          <li>Images</li>
          <li>Rankings</li>
          <li>Translations</li>
        </ul>
      </li>
    </ul>
  </Step>

<Step title="Save to Activate">
    Once you've configured all settings, save your survey to activate the email follow-up.
  </Step>
</Steps>

# Hidden Fields
Source: https://formbricks.com/docs/surveys/general-features/hidden-fields

Add data to a submission without asking the user to type it in. This feature is especially useful when you already have information about a user that you want to use in the analysis of the survey results (e.g. `payment plan` or `email`).

## How to Add Hidden Fields

### Enable Hidden Fields

1. Edit the survey you want to add hidden fields to & switch to the Questions tab and scroll down to the bottom of the page. You will see a section called **Hidden Fields**. Make sure to enable it by toggling the switch.

### Add Hidden Field IDs

1. Now click on it to add a new hidden field ID. You can add as many hidden fields as you want.

## Set Hidden Field via URL

Single Hidden Field:

```
https://formbricks.com/s/clin34bjy?screen=pricing
```

Multiple Hidden Fields:

```
https://formbricks.com/s/clin34bjy?screen=landing_page&job=Founder
```

## Set Hidden Fields via SDK

<Note>
  We are reworking how to add Hidden Fields via SDK moving away from binding them to Actions over to Context. Until then, we will **continue to support the current approach for the JS SDK**. However, we don't support Hidden Fields for the Android and iOS SDKs.
</Note>

```js theme={null}
formbricks.track("action_name", {hiddenFields: {myField: "value"}})
```

## View Hidden Fields in Responses

These hidden fields will now be visible in the responses tab just like other fields in the Summary as well as the Response Cards, and you can use them to filter and analyze your responses.

## Use Cases

* **Tracking Source**: You can add a hidden field to track the source of the survey. For a detailed guide on Source Tracking, check out the [Source Tracking](/docs/surveys/link-surveys/source-tracking) guide.

* **User Metadata**: You can add hidden fields to capture user metadata such as user ID, email, or any other user-specific information.

* **Survey Metadata**: You can add hidden fields to capture other metadata, e.g. the screen from which the survey was filled, or any other app specific information.

# Hide Back Button
Source: https://formbricks.com/docs/surveys/general-features/hide-back-button

Learn how to hide the back button in surveys.

Surveys display a back button by default. If you want to prevent respondents from returning to previous questions, you'll need to disable this feature explicitly.

To disable the back button, navigate to the survey settings and select the Response options tab.

# Limit Submissions
Source: https://formbricks.com/docs/surveys/general-features/limit-submissions

Automatically close your survey after reaching a set number of responses in Formbricks. This is useful for limited offers, exclusive surveys, or when you need a specific sample size.

* **How to**: Open the Survey Editor, switch to the Settings tab. Scroll down to **Response Options**, and toggle the **“Close survey on response limit”**.

* **Details**: Set a specific number of responses after which the survey automatically closes.

* **Use Case**: Perfect for limited offers, exclusive surveys, or when you need a precise sample size for statistical significance.

# User Metadata
Source: https://formbricks.com/docs/surveys/general-features/metadata

Formbricks captures metadata of your users for you when they fill a survey. This metadata is useful for understanding the context in which the user filled the survey. For example, if you are running a marketing campaign, you can understand which source is driving the most responses. Or if you are running a survey on a specific page, you can understand the user's behavior on that page.

## Metadata Captured

* **Source**: The source from where the user filled the survey. This could be an App, Link, or a Webpage.

* **URL**: The URL of the page where the user filled the survey.

* **Browser**: The browser used by the user to fill the survey.

* **OS**: The operating system of the device used by the user to fill the survey.

* **Device**: The device used by the user to fill the survey.

* **Country**: The country of the user.

* **Action**: The action that triggered the survey. This is only available for App surveys.

## View Response Metadata

1. Go to the Responses tab of your survey.

2. Hover over the profile icon of the user on the response card & you should see a tooltip opening up with the metadata details.

## Filter Responses by Metadata

1. Go to the Responses tab of your survey.

2. Click on the Filter button.

3. Scroll down & Select the metadata field you want to filter by.

4. Select the condition & the value you want to filter by.

1. Now you should see the responses filtered based on the metadata you selected. If you want to see a walkthrough, view the video above to see how you can view & filter responses by metadata.

## Export Metadata

You can export the metadata of your responses along with the response data. When you export responses, you will see the metadata fields in the exported CSV file.

***

**Need help?** [Reach out in Github Discussions](https://github.com/formbricks/formbricks/discussions)

# Multi-language Surveys
Source: https://formbricks.com/docs/surveys/general-features/multi-language-surveys

Create surveys that support multiple languages using translations. This helps you reach a diverse audience without making separate surveys for each language. It also simplifies survey creation, delivery, and analysis for multilingual audiences.

How to deliver a specific language depends on the survey type (app or link survey):

* App & Website survey: Set a `language` attribute for the user. [Read this guide for App Surveys](#app-surveys-configuration)

* Link survey: Add a `lang` parameter in the survey URL. [Read this guide for Link Surveys](#link-surveys-configuration)

***

## Creating a Multi-language Survey

<Steps>
  <Step title="Configure Survey Languages">
    Go to Configuration and open the **Survey Languages tab**:

Click on the **Edit languages** button to add a new language to your survey.

Select the preferred language from the dropdown and assign an identifier Alias. Click the **Add language** button to add the language to your Workspace:

You can come back to this page anytime to add more languages or remove existing ones.
  </Step>

<Step title="Create or Edit Your Survey">
    Return to the dashboard to create a new survey or edit an existing one:

<Step title="Enable Multi-language Support">
    In the survey editor, scroll down to the **Multiple Languages** section at the bottom and enable the toggle next to it:

Choose a **Default Language** for your survey.

<Note>Changing the default language will reset all the translations you have made for the survey.</Note>
  </Step>

<Step title="Add Supported Languages">
    Add the languages from the dropdown that you want to support in your survey:

<Step title="Preview and Translate Content">
    You can now see the survey in the selected language by clicking on the language dropdown in any of the questions.

Now you can translate all survey content, including questions, options, and button placeholders, into the selected language.
  </Step>

<Step title="Publish Your Survey">
    Once you are done, click on the **Publish** button to save the survey.
  </Step>
</Steps>

***

## Built-in Interface Translations

Beyond the content you translate yourself, every survey ships with a set of built-in interface strings that Formbricks localizes automatically — so respondents see them in their own language without any extra work from you. These include:

* Default navigation and action buttons (**Back**, **Next**, **Finish**)
* Form validation messages (e.g. "Please fill out this field", "Please enter a valid email address")
* File-upload prompts and states
* Offline, retry, and "sending responses" notices
* Attribution and helper labels like "Powered by" and "Required"

These built-in strings are currently provided in **23 languages**:

| Language              | Code         | Language            | Code    |
| --------------------- | ------------ | ------------------- | ------- |
| English (base)        | `en-US`      | Italian             | `it-IT` |
| Arabic                | `ar-EG`      | Japanese            | `ja-JP` |
| Chinese (Simplified)  | `zh-Hans-CN` | Portuguese (Brazil) | `pt-BR` |
| Chinese (Traditional) | `zh-Hant-TW` | Romanian            | `ro-RO` |
| Danish                | `da-DK`      | Russian             | `ru-RU` |
| Dutch                 | `nl-NL`      | Spanish             | `es-ES` |
| Estonian              | `et-EE`      | Swedish             | `sv-SE` |
| French                | `fr-FR`      | Turkish             | `tr-TR` |
| German                | `de-DE`      | Urdu                | `ur-PK` |
| Hindi                 | `hi-IN`      | Uzbek               | `uz-UZ` |
| Hungarian             | `hu-HU`      | Vietnamese          | `vi-VN` |
| Indonesian            | `id-ID`      |                     |         |

Formbricks matches the survey's active language to the closest available bundle — for example, `de-AT` and `de` both use the German bundle, and `pt-PT` uses `pt-BR`. Writing script is preserved when matching, so `zh-Hant` and `zh-TW` resolve to the Traditional Chinese bundle rather than the Simplified one. If a language has no matching bundle, your translated survey content is still shown as usual, but these built-in interface strings fall back to English.

<Note>
  Don't see your language? These interface translations live in the open-source `@formbricks/surveys` package. You can add a new one by contributing a locale file on [GitHub](https://github.com/formbricks/formbricks).
</Note>

***

## App Surveys Configuration

<Steps>
  <Step title="Set Up Language for Users">
    After you setup the Formbricks SDK for your user, you can call the `setLanguage` function with the language code. This can be either the ISO identifier or the Alias you set when creating the language. The `language` attribute makes sure that this user only sees surveys with a translation in this specific language available.

```js theme={null}
    Formbricks.setup({
      workspaceId: "<workspace-id>",
      appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
    });

Formbricks.setLanguage("de"); // ISO identifier or Alias set when creating language
    ```

<Note>
      If a user has a language assigned, a survey has multi-language activated and it is missing a translation in
      the language of the user, the survey will not be displayed.
    </Note>
  </Step>

<Step title="Start Collecting Responses">
    That's it! Now, users with the language attribute set will see the survey in their preferred language. You can start collecting responses in multiple languages and filter them by language on the summary page.
  </Step>
</Steps>

***

## Link Surveys Configuration

For link surveys, the translation delivery is dependent on the `lang` URL parameter.

<Steps>
  <Step title="Publish Your Survey">
    After publishing the survey, just copy the survey link and append the `lang` query parameter with the language alias you have set.
  </Step>

<Step title="Create Language-Specific URLs">
    For example, if you have set the alias for French as `fr`, you can share the survey link as

[`https://your-survey-url.com?lang=fr`](https://your-survey-url.com?lang=fr)

Here are two examples:

* English: [https://app.Formbricks.com/s/clptfos2i1pj516pvhxqyu3bn?lang=en](https://app.Formbricks.com/s/clptfos2i1pj516pvhxqyu3bn?lang=en)

* German: [https://app.Formbricks.com/s/clptfos2i1pj516pvhxqyu3bn?lang=de](https://app.Formbricks.com/s/clptfos2i1pj516pvhxqyu3bn?lang=de)

Without the `lang` parameter, Formbricks will show the survey in the default language you have set.
  </Step>

<Step title="Start Collecting Responses">
    You can now start collecting responses in multiple languages!
  </Step>
</Steps>

***

## Translate with AI

Translating every question, option, and label by hand can take a while. If your organization has AI enabled, you can fill in missing translations in one click.

<Steps>
  <Step title="Open the Manage Translations modal">
    Inside the survey editor, switch to the language you want to translate into and open the **Manage Translations** modal.
  </Step>

<Step title="Click 'Translate with AI'">
    The button is enabled when there are empty fields in the selected target language. Formbricks translates all empty headlines, descriptions, choices, and button labels from the default language into the target language.
  </Step>

<Step title="Review and edit">
    AI-translated strings are filled into the editor like manual translations. Review them before publishing and tweak anything that needs a different tone or wording.
  </Step>
</Steps>

<Note>
  AI translation is an [Enterprise feature](/docs/self-hosting/advanced/license) and requires **Smart functionality (AI)** to be enabled at the organization level. See [AI Features](/docs/platform/features/ai-features).
</Note>

***

## RTL Language Support

Formbricks fully supports Right-to-Left (RTL) languages such as Arabic, Hebrew, Persian, and Urdu. When you add an RTL language to your survey, the survey interface automatically adjusts to display content from right to left.

### How RTL Support Works

* Text alignment automatically switches to right-to-left
* Survey layout and UI elements adjust to RTL orientation
* Button placement and navigation flow adapt to RTL reading direction
* Form elements maintain proper RTL formatting

### Setting Up RTL Languages

<Steps>
  <Step title="Add RTL Language">
    Add an RTL language (like Arabic or Hebrew) in the **Survey Languages** settings
  </Step>

<Step title="Create Translations">
    Create translations for your survey content in the RTL language
  </Step>

<Step title="Automatic RTL Display">
    The survey will automatically display in RTL format when that language is selected

***

**Need help?** [Reach out in Github Discussions](https://github.com/formbricks/formbricks/discussions)

# Custom Styling
Source: https://formbricks.com/docs/surveys/general-features/overwrite-styling

Overwrite the global styling theme for individual surveys to create unique styles for each survey.

<Note>
  To set a styling theme for all surveys, please see the [Styling Theme](/docs/platform/features/styling-theme) manual.
</Note>

## Overwrite Styling Theme

1. In the **Survey Editor** of the survey you want to style, navigate to the **Styling** tab:

2. Activate the **Add Custom Styles** toggle to override the default Workspace styling:

3. Customize your survey's style as needed:

Just hit the **Save** button to apply your changes. Your survey is now ready to impress with its unique look!

## Overwrite CSS Styles for App & Website Surveys

You can overwrite the default CSS styles for app and website surveys by adding the following CSS to your global CSS file (e.g., `globals.css`):

**Do not** change the CSS variable names, as Formbricks uses them to identify styling elements. You can adjust the values to fit your design. Below are sample values for reference:

```css theme={null}
/* Overwrite Formbricks default styles */
--fb-brand-color: red;
--fb-brand-text-color: white;
--fb-border-color: green;
--fb-border-color-highlight: rgb(13, 13, 12);
--fb-focus-color: red;
--fb-heading-color: yellow;
--fb-subheading-color: green;
--fb-info-text-color: orange;
--fb-signature-text-color: blue;
--fb-survey-background-color: black;
--fb-accent-background-color: rgb(13, 13, 12);
--fb-accent-background-color-selected: red;
--fb-placeholder-color: white;
--fb-rating-fill: rgb(13, 13, 12);
--fb-rating-hover: green;
--fb-back-btn-border: blue;
--fb-submit-btn-border: transparent;
--fb-rating-selected: black;
```

Check out an example in our Demo Workspace.

Funky Survey Examples
Super Mario
"I guess he won't let himself be limited by radio buttons and do all three things!"

Hipster Living
"Does your monstera get enough water?"

Windows XP
"Hach, nostalgia. It made us want to play Mafia."

Who's a Good Boy?
"Things you've likely said to your dog."

# Partial Submissions
Source: https://formbricks.com/docs/surveys/general-features/partial-submissions

Capture and analyze partial submissions, providing detailed insights into how participants interact with each question within your survey. This feature is crucial for identifying specific points where respondents may disengage, allowing you to understand and address drop-offs effectively.

## **Understanding Partial Submissions**

Partial submissions occur when respondents start a survey but do not complete it. These can include instances where the survey is opened but no questions are answered, or where only some questions are addressed before the survey is exited.

## **Enabling and Accessing Partial Submissions Tracking**

Tracking of partial submissions is automatically enabled for all Formbricks surveys, capturing every interaction from the moment a respondent begins the survey.

### **Types of Data Captured**

1. **Display Created**: Tracks when a survey is initially opened.

2. **Questions Partially Answered**: Records after every question & the data is handled, noting which questions were last interacted with before the survey was exited.

### **Benefits of Tracking Partial Submissions**

* **Identifies Drop-Off Points**: Pinpoints specific questions where respondents are likely to stop answering, providing critical insights into potential issues within the survey.

* **Improves Survey Design**: Data from partial submissions can guide adjustments to question complexity, survey length, or formatting to enhance respondent engagement.

* **Enhances Completion Rates**: Understanding where and why respondents are dropping off allows for targeted interventions to improve overall engagement and completion rates.

## **Analyzing Partial Submission Data**

Formbricks provides detailed analytics for partial submissions, including a per-question analysis of respondent behavior.

### **Survey Summary Analytics**

The "Analyze Drop-Offs" toggle in the survey summary reveals a comprehensive table with detailed metrics, enabling a deep dive into how respondents interact with each question:

* **Summary Metrics**:

* **Impressions**: Total number of times the survey was viewed.

* **Starts**: Percentage of impressions that the survey was started.

* **Responses**: Total number of completed responses.

* **Drop-Offs**: Percentage of starts that did not lead to a complete response.

* **Time to Complete**: Average time taken by respondents to complete the survey.

### **Detailed Question Analysis**

Each question is analyzed for:

* **Time to Complete**: Average time taken by respondents spent on this question.

* **Impressions**: Number of times the question was viewed.

* **Drop-Offs**: Number of times respondents left the survey at this question, with a percentage indicating the drop-off rate.

This data is invaluable for pinpointing problems with specific questions and understanding the overall flow and engagement levels within the survey.

## **Use Cases**

Partial submissions tracking is particularly valuable for:

* Surveys experiencing high drop-off rates, where detailed question analysis can inform necessary adjustments.

* Studies requiring in-depth engagement metrics for each survey question to optimize content and survey structure.

## **Conclusion**

By leveraging the partial submissions tracking feature in Formbricks, you gain comprehensive insights into respondent behaviors and survey interactions. This information is vital for enhancing survey design, improving response rates, and ensuring more reliable and meaningful data collection.

# Quota Management
Source: https://formbricks.com/docs/surveys/general-features/quota-management

Control response collection by setting limits on specific segments to ensure balanced and representative survey datasets.

## Overview

Quota Management allows you to set limits on the number of responses collected for specific segments or criteria in your survey. This feature helps ensure you collect a balanced and representative dataset while preventing oversaturation of certain response types.

<Note>
  Quota Management is part of the [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

### Key benefits

* **Balanced Data Collection**: Ensure your survey responses are evenly distributed across different segments
* **Cost Control**: Prevent collecting more responses than needed from specific groups
* **Quality Assurance**: Maintain data quality by avoiding homogeneous response patterns
* **Automated Management**: Automatically stop collecting responses when quotas are met

### How Quota Management works

When you set up quotas for your survey, Formbricks automatically tracks responses against your defined limits. Once a quota is reached, the system can:

* Prevent new responses from that segment
* Skip respondents to the end of the survey
* Redirect respondents to a custom end screen

## Setting up Quotas

In the first step, you need to define the criteria for the quota:

<Steps>
  <Step title="Name the quota">
    Create a Quota and label it e.g. "Mobile Phone Users in Europe"
  </Step>

<Step title="Set quota limit">
    Set numerical limits for each hidden field value combination e.g. 500
  </Step>

<Step title="Define inclusion criteria">
    Choose a distinct set of answers to survey questions, variable values or hidden fields. Responses who match this set will be included in the quota.
  </Step>

<Step title="Configure actions">
    Choose what happens when this Quota is met (e.g. skip to specific end screen)
  </Step>
</Steps>

## Quota actions

Configure what happens when a quota reaches its limit:

<Tabs>
  <Tab title="Skip to End">
    Jump respondents directly to the survey completion page
  </Tab>

<Tab title="Custom Redirect (soon)">
    Redirect respondents to a custom thank you page or alternative survey
  </Tab>
</Tabs>

## Counting against Quotas

### 1. Count by Hidden Field value

Determine if a response falls in or out of a Quota based on hidden field values passed through URL parameters:

```
https://your-survey-url.com/s/abc123?product=credit-card®ion=europe
```

### 2. Quota by survey responses

Create quotas based on specific answers to survey questions:

<Tabs>
  <Tab title="Single Question Quota">
    Set quotas for individual answer options:

* Question: "What is your gender?"
    * Quota: 500 responses for "Male", 500 responses for "Female"
  </Tab>

<Tab title="Multi-Question Quota">
    Combine multiple question responses:

* Criteria: Age group "25-34" AND Location "Urban"
    * Quota: 200 responses matching both criteria
  </Tab>
</Tabs>

### 3. Multi-criteria quotas

Create complex quotas using multiple conditions:

<CodeGroup>
  ```example "Hidden Field + Response Combination" theme={null}
  Hidden Field: product = "mobile"
  AND
  Question Response: satisfaction = "very satisfied"
  ```

```example "Multiple Response Criteria" theme={null}
  Question 1: age_group = "18-25"
  AND
  Question 2: location = "urban"
  AND
  Question 3: income = "high"
  Quota Limit: 50 responses
  ```
</CodeGroup>

### Partial vs. complete responses

<Info>
  By default, Quota Management includes partial responses in quota counts. You can change this behavior by configuring the quota to only count complete responses.
</Info>

This means if a respondent starts but doesn't complete the survey, they may still count toward your quota if they've answered the qualifying questions.

## Quota monitoring

<Card title="Live Quota Status" icon="chart-line">
  Monitor your quotas in real-time through the dashboard in the survey summary:

* **Current Count**: See how many responses each quota has collected
  * **Progress Bars**: Visual representation of quota completion
  * **Status Indicators**: Active, completed, or paused quota status
</Card>

# Recall Data
Source: https://formbricks.com/docs/surveys/general-features/recall

Personalize your surveys by dynamically inserting data from URL parameters or previous answers into questions and descriptions. The Recall Data feature helps create engaging, adaptive survey experiences tailored to each respondent.

## Recall Sources

You can recall data from the following sources:

* From a previous question

* From a [Hidden Field](/docs/surveys/general-features/hidden-fields)

* From a [Variable](/docs/surveys/general-features/variables)

## Recalling from a previous question

<Note>
  The recall functionality is disabled on the first question of the survey since
  there’s no preceding question to recall data from.
</Note>

### **Pre-requisite**

Ensure the answer you wish to recall precedes the question in which it will be recalled. Here’s an example of setting up the first question:

### **Step 1: Recall Data**

Type **`@`** in the question or description field where you want to insert a recall. This triggers a dropdown menu listing all preceding questions. Select the question you want to recall data from.

### **Step 2: Set a Fallback**

To ensure the survey remains coherent when a response is missing (or the question is optional), you should set a fallback option.

## Recalling from the URL

1. Create a hidden field, [here is how →](/docs/surveys/general-features/hidden-fields)

2. Use the `@` symbol in a question or description to recall the value of the hidden field

3. Set a fallback in case the hidden field is not being filled by a URL parameter

4. Use [Data Prefilling](/docs/surveys/link-surveys/data-prefilling) to set the hidden field value when the survey is accessed

## Recalling from a Variable

1. Create a variable, [here is how →](/docs/surveys/general-features/variables)

2. Use the `@` symbol in a question or description to recall the value of the variable

3. Set a fallback in case the variable is not being filled by a URL parameter

## Live Demo

## **Conclusion**

Recall Data in Formbricks surveys allows for a conversational and customized survey experience that enhances engagement and improves the quality of feedback. By integrating previous responses into new questions, you create a more interactive and relevant environment for respondents.

# Spam Protection
Source: https://formbricks.com/docs/surveys/general-features/spam-protection

Enable spam protection for your surveys using Google reCAPTCHA v3.

## Overview

Spam protection feature protects your Formbricks instance from spam and automated abuse by verifying that survey responses are submitted by real users. This guide explains how to enable and configure spam protection in your Formbricks instance using Google reCAPTCHA v3.

<Note>
  Spam protection is a paid feature. It is only available for users on paid plans or if you have [Enterprise
  Edition](/docs/self-hosting/advanced/license).
</Note>

<Note>
  Spam protection does <strong>not</strong> work for surveys displayed with the Mobile SDKs(React Native, iOS,
  or Android SDKs). Enabling this setting in the Survey Editor will break the survey in those environments.
</Note>

## Key Generation

To use spam protection, you need to generate a Site Key and Secret Key:

1. Go to the [Google reCAPTCHA admin console](https://www.google.com/recaptcha/admin/create).
2. Register a new site:
   * **Label:** Any name (e.g., "Formbricks Self-Hosted")
   * **reCAPTCHA type:** Select **reCAPTCHA v3**
   * **Domains:** Add your domain (e.g., `yourdomain.com`). For local development, add `localhost`.
   * Accept the terms and submit.
3. Copy the generated **Site Key** and **Secret Key**.

> **Note:** Keep your Secret Key private and never expose it in client-side code.

## Configuration

Add the following environment variables to your `.env` file or deployment environment:

```bash theme={null}
RECAPTCHA_SITE_KEY=your_site_key_here
RECAPTCHA_SECRET_KEY=your_secret_key_here
```

Restart your application after setting these variables.

## Firewall & Network Requirements

If your self-hosted Formbricks instance is behind a firewall or proxy, ensure it can reach the Google reCAPTCHA verification endpoint:

* `https://www.google.com/recaptcha/api/siteverify`

Allow outbound HTTPS (TCP port 443) traffic to this domain.

## Steps to Enable Spam Protection

You can enable Google reCAPTCHA v3 spam protection for your survey directly from the Formbricks Survey Editor. This helps prevent automated and spammy responses.

<Steps>
  <Step title="Open the Survey Editor">
    Navigate to the Survey Editor.
  </Step>

<Step title="Go to the Settings Tab">
    Click on the **Settings** tab next to the Questions & Styling tab.
  </Step>

<Step title="Find Spam Protection Option">
    Scroll down to the **Response Options** and find the **Spam Protection** option.
  </Step>

<Step title="Enable Spam Protection">
    Toggle the **Spam Protection** option to activate spam protection for this survey.
  </Step>

<Step title="Set the reCAPTCHA Threshold">
    Adjust the **response threshold**. This is the score threshold for accepting or rejecting responses. A lower threshold (e.g., 0.1) is lenient, while a higher threshold (e.g., 0.9) is strict.

<Step title="Save Your Changes">
    Click **Save** to apply spam protection settings to your survey.
  </Step>
</Steps>

Once enabled, all survey responses will be checked using Google reCAPTCHA v3 before being accepted.

For help, join the conversation on [GitHub Discussions](https://github.com/formbricks/formbricks/discussions).

# Tags
Source: https://formbricks.com/docs/surveys/general-features/tags

Organize and categorize survey responses to easily filter, analyze, and manage your data.

## What are Tags?

Tags are labels that you can apply to individual survey responses. They allow you to:

* Categorize responses by topic, sentiment, or any custom criteria
* Filter responses to find specific subsets of data
* Track and organize feedback across multiple surveys
* Simplify analysis and reporting workflows

Tags are environment-specific, meaning each environment maintains its own set of tags.

## Add tags to responses

<Steps>
  <Step title="Navigate to responses">
    Go to the **Responses** tab of your survey.
  </Step>

<Step title="Open a response">
    Click on any response card to view the full response details.
  </Step>

<Step title="Add a tag">
    At the bottom of the response card, click the **Add Tag** button.
  </Step>

<Step title="Select or create a tag">
    * Select an existing tag from the dropdown list, or
    * Type a new tag name and click **+ Add \[tag name]** to create a new tag
  </Step>
</Steps>

The tag will be immediately applied to the response. You can add multiple tags to a single response.

## Remove tags from responses

To remove a tag from a response:

1. Open the response card
2. Click the **X** icon on the tag you want to remove

The tag will be removed from the response immediately.

## Manage tags

Access the tag management page to view and organize all tags in your environment.

<Steps>
  <Step title="Navigate to Configuration">
    Click on **Workspace Configuration** > **Tags**.
  </Step>

<Step title="View all tags">
    You'll see a list of all tags in your environment with their usage count showing how many responses have each tag applied.
  </Step>
</Steps>

### Edit tag names

1. In the tag management page, click on the tag name field
2. Edit the name directly
3. Click outside the field or press Enter to save

<Note>
  Tag names must be unique within an environment. If you try to use an existing tag name, you'll receive an error.
</Note>

### Merge tags

Merging tags is useful when you have duplicate or similar tags that you want to consolidate.

1. In the tag management page, find the tag you want to merge
2. Click the **Merge into** dropdown
3. Select the destination tag
4. Confirm the merge

All responses tagged with the original tag will be updated to use the destination tag, and the original tag will be deleted.

### Delete tags

1. In the tag management page, find the tag you want to delete
2. Click the **Delete** button
3. Confirm the deletion

<Warning>
  Deleting a tag will remove it from all responses. This action cannot be undone.
</Warning>

## Filter responses by tags

Use tags to filter and find specific responses in your survey analysis.

<Steps>
  <Step title="Open filters">
    In the **Responses** tab, click the **Filter** button.
  </Step>

<Step title="Select tag filter">
    Scroll to the **Tags** section and select a tag from the dropdown.
  </Step>

<Step title="Choose filter type">
    Choose whether to filter by:

* **Applied**: Show only responses that have this tag
    * **Not Applied**: Show only responses that don't have this tag
  </Step>

<Step title="View filtered results">
    The response list will update to show only responses matching your tag filter.
  </Step>
</Steps>

You can combine tag filters with other filters (questions, attributes, metadata) to create complex filter criteria.

## Use cases

Here are some common ways to use tags:

* **Sentiment tracking**: Tag responses as "positive", "negative", or "neutral"
* **Follow-up needed**: Mark responses that require action with a "follow-up" tag
* **Feature requests**: Categorize feedback by product area or feature
* **Customer segments**: Tag responses by customer type, industry, or plan level
* **Priority levels**: Mark critical issues with "urgent" or "high-priority" tags
* **Review status**: Track which responses have been reviewed with "reviewed" or "pending" tags

## Permissions

Tag management requires appropriate permissions:

* **View tags**: All users with access to the Workspace can view tags on responses
* **Add/remove tags on responses**: Users with read-write access can apply and remove tags
* **Manage tags** (create, edit, merge, delete): Users with Workspace team read-write permission or organization owner/manager roles

***

**Need help?** [Reach out in Github Discussions](https://github.com/formbricks/formbricks/discussions)

# Validation Rules
Source: https://formbricks.com/docs/surveys/general-features/validation-rules

Validation rules help you ensure that respondents provide data in the correct format and within expected constraints

By adding validation rules to your questions, you can improve data quality, reduce errors, and create a better survey experience.

## How Validation Rules Work

Validation rules are evaluated when a respondent submits their answer. If the answer doesn't meet the validation criteria, an error message is displayed and the respondent must correct their input before proceeding.

You can combine multiple validation rules using **All are true** or **Any is true** logic:

* **All are true**: All rules must pass for the response to be valid
* **Any is true**: At least one rule must pass for the response to be valid

## Available Validation Rules by Question Type

### Free Text Questions

Free text questions support different validation rules based on the input type:

#### Text Input Type

| Rule                  | Description                          | Example                                      |
| --------------------- | ------------------------------------ | -------------------------------------------- |
| At least (characters) | Requires at least N characters       | At least 10 characters for detailed feedback |
| At most (characters)  | Limits response to N characters      | At most 500 characters for short answers     |
| Matches Regex Pattern | Matches a regular expression pattern | Custom format validation                     |
| Is                    | Exact match required                 | Must equal "CONFIRM"                         |
| Is not                | Must not match the value             | Cannot be "N/A"                              |
| Contains              | Must include the substring           | Must contain "@company.com"                  |
| Does not contain      | Must not include the substring       | Cannot contain profanity                     |

#### Email Input Type

Email input automatically validates email format. Additional rules available:

* At least, At most (characters)
* Matches Regex Pattern, Is, Is not
* Contains, Does not contain

#### URL Input Type

URL input automatically validates URL format. Additional rules available:

* At least, At most (characters)
* Matches Regex Pattern, Is, Is not
* Contains, Does not contain

#### Phone Input Type

Phone input automatically validates phone number format. Additional rules available:

* At least, At most (characters)
* Matches Regex Pattern, Is, Is not
* Contains, Does not contain

#### Number Input Type

| Rule     | Description               | Example                 |
| -------- | ------------------------- | ----------------------- |
| At least | Number must be at least N | Age must be at least 18 |
| At most  | Number cannot exceed N    | Quantity at most 100    |
| Is       | Number must equal N       | Quantity is 1           |
| Is not   | Number must not equal N   | Cannot be 0             |

### Multiple Choice (Multi-Select) Questions

| Rule                        | Description                   | Example                     |
| --------------------------- | ----------------------------- | --------------------------- |
| At least (options selected) | Require at least N selections | At least 2 options selected |
| At most (options selected)  | Limit to N selections         | At most 3 options selected  |

### Picture Selection Questions

| Rule                        | Description                 | Example                      |
| --------------------------- | --------------------------- | ---------------------------- |
| At least (options selected) | Require at least N pictures | At least 1 design selected   |
| At most (options selected)  | Limit to N pictures         | At most 2 favorites selected |

### Date Questions

| Rule            | Description                        | Example                     |
| --------------- | ---------------------------------- | --------------------------- |
| Is later than   | Date must be after specified date  | Must be after today         |
| Is earlier than | Date must be before specified date | Must be before Dec 31, 2025 |
| Is between      | Date must be within range          | Between Jan 1 and Dec 31    |
| Is not between  | Date must be outside range         | Cannot be during holidays   |

<Note>
  Date values should be specified in YYYY-MM-DD format (e.g., 2025-01-15).
</Note>

### Matrix Questions

| Rule                  | Description                            | Example                    |
| --------------------- | -------------------------------------- | -------------------------- |
| Minimum rows answered | Require at least N rows to be answered | Answer at least 3 rows     |
| Answer all rows       | All rows must have a selection         | Complete the entire matrix |

### Ranking Questions

| Rule                   | Description                           | Example          |
| ---------------------- | ------------------------------------- | ---------------- |
| Minimum options ranked | Require at least N items to be ranked | Rank your top 3  |
| Rank all options       | All options must be ranked            | Rank all 5 items |

### File Upload Questions

| Rule                  | Description                    | Example                  |
| --------------------- | ------------------------------ | ------------------------ |
| File extension is     | Only allow specific file types | Only .pdf, .docx allowed |
| File extension is not | Block specific file types      | No .exe files            |

<Note>
  File size limits are configured separately in the question settings using the "Maximum file size" option.
</Note>

### Address Questions

Each address field (Address Line 1, Address Line 2, City, State, ZIP, Country) can have its own validation rules:

* At least, At most (characters)
* Matches Regex Pattern
* Is, Is not
* Contains, Does not contain

### Contact Info Questions

Each contact field can have specific validation rules:

**First Name, Last Name, Company**:

* At least, At most (characters)
* Matches Regex Pattern, Is, Is not
* Contains, Does not contain

**Email**: Automatically validates email format, plus text rules above

**Phone**: Automatically validates phone format, plus text rules above

## Adding Validation Rules

<Steps>
  <Step title="Open the Question Settings">
    Click on the question you want to validate to open its settings panel.
  </Step>

<Step title="Navigate to Validation Rules">
    Scroll down to find the "Validation Rules" section and click to expand it.
  </Step>

<Step title="Add a Rule">
    Click the "Add rule" button to add a new validation rule.
  </Step>

<Step title="Configure the Rule">
    Select the rule type from the dropdown and enter the required value (if applicable).
  </Step>

<Step title="Set Logic (Optional)">
    If you have multiple rules, choose whether they should be combined with "All are true" or "Any is true" logic.
  </Step>

<Step title="Save Your Survey">
    Click "Save" to apply the validation rules to your survey.
  </Step>
</Steps>

## Error Messages

Formbricks automatically generates user-friendly error messages based on your validation rules. Error messages are displayed below the input field when validation fails.

Example error messages:

* "Must be at least 10 characters"
* "Must be a valid email address"
* "Please select at least 2 options"
* "Date must be after 2025-01-01"

## Multi-Language Support

Validation rules work with multi-language surveys. Error messages are automatically displayed in the respondent's selected language.

## Combining Multiple Rules

When using multiple validation rules:

**All are true**: Use when all conditions must be met.

* Example: Text must be at least 10 characters AND contain "@email.com"

**Any is true**: Use when any condition is acceptable.

* Example: Date is earlier than 2025-01-01 OR is later than 2025-12-31

# Variables
Source: https://formbricks.com/docs/surveys/general-features/variables

Variables are a powerful feature in Formbricks that allows you to keep track of data variables when user fills a form. This feature is especially useful when you want to use your survey as a quiz.

## Types of Variables

There are two types of variables you can add to your survey:

1. **Text**: You can add text variables to your survey to capture text data.

2. **Number**: You can add number variables to your survey to capture number data.

## How to Add Variables

1. Edit the survey you want to add variables to & switch to the Questions tab and scroll down to the bottom of the page. You will see a section called **Variables**.

1. Now click on it to add a new variable ID. You can add as many variables as you want. You can also choose the type of variable you want to add along with the default value.

## Use cases

* **Quiz**: You can use variables to create a quiz. For example, you can add a variable `score` and update it every time a user answers a question. You can also use the variable for recall to show the final score to the user.

* **Personalisation**: You can use variables to store user data and personalise the survey experience. For example, you can add a variable `full_name` and update it every time a user fills in their first name and last name. You can use the variable to personalise the survey experience by addressing the user with their full name.

## How is it different from Hidden Fields?

Variables are different from hidden fields in the following ways:

1. **Setting**: Hidden fields can be set through query parameters or `formbricks.init`, but the variables can only be set either during creation or dynamically by using logic actions.

2. **Updating**: Hidden fields cannot be set again, but the value of variables can be updated while the user fills the survey.

3. **Type**: Hidden fields can only store text data, but variables can store both text and number data.

## How to use Variables

1. Once you have added the variables to your survey, you'll be able to access them in the logic editor. You can use the variables to create logic actions and conditions.

1. You can create logic based on the variables and questions in your survey and can update the variables based on the user's response.

### Recalling Variables in the Survey

You can recall show the variable value to the respondent by using the [Recall Data](/docs/surveys/general-features/recall) function.

<Note>
  To know more about how to use logic in Formbricks, check out the [Conditional
  Logic](/docs/surveys/general-features/conditional-logic).
</Note>

# Custom Head Scripts
Source: https://formbricks.com/docs/surveys/link-surveys/custom-head-scripts

Add tracking pixels, analytics, or custom code to your link surveys for self-hosted instances.

Custom Head Scripts allow you to inject custom HTML code into the `<head>` section of your **Link Surveys**. This is useful for adding tracking pixels, analytics scripts, chatbots, or any other third-party code.

<Note>
  Custom Head Scripts is only available for **Link Surveys on self-hosted instances**. This feature is not available for Website & App Surveys or on Formbricks Cloud.
</Note>

## When to Use Custom Head Scripts

Use Custom Head Scripts when you need to:

* Add analytics tools (Google Analytics, Plausible, Mixpanel, etc.)
* Integrate tracking pixels (Facebook Pixel, LinkedIn Insight Tag, etc.)
* Include custom JavaScript for advanced survey behavior
* Add third-party widgets or chatbots
* Inject custom meta tags or stylesheets

## Configuration Guide

### Workspace-Level Scripts

These scripts apply to **all link surveys** in your workspace.

<Steps>
  <Step title="Navigate to Settings → Workspace → General">
    Go to **Settings → Workspace → General** from the main navigation menu.
  </Step>

<Step title="Locate Custom Scripts Section">
    Scroll down to the **Custom Scripts** card on the General page.
  </Step>

<Step title="Add Your Scripts">
    Paste your HTML code into the text area. You can include:

* `<script>` tags (inline or with `src` attribute)
    * `<meta>` tags
    * `<link>` tags for stylesheets
    * `<style>` tags
    * `<noscript>` tags

**Example:**

```html theme={null}
    
    <script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'GA_MEASUREMENT_ID');
    </script>
    ```
  </Step>

<Step title="Save Your Changes">
    Click the **Save** button to apply your custom scripts to all link surveys.
  </Step>
</Steps>

### Survey-Level Scripts

Override or extend workspace scripts for **specific surveys**.

<Steps>
  <Step title="Open Share Survey Modal">
    Navigate to your survey and click the **Share** button to open the share modal.
  </Step>

<Step title="Go to Custom HTML Tab">
    In the share modal, click on the **Custom HTML** tab under the "Share Settings" section.
  </Step>

<Step title="Choose Script Mode">
    Select how you want survey scripts to interact with workspace scripts:

* **Add to Workspace Scripts** - Survey scripts will be added **after** workspace scripts (both run)
    * **Replace Workspace Scripts** - Survey scripts will **replace** workspace scripts entirely (only survey scripts run)
  </Step>

<Step title="Add Survey-Specific Scripts">
    Paste your HTML code into the "Survey Scripts" text area.

**Example** (Facebook Pixel for a specific campaign):

```html theme={null}
    
    <script>
      fbq('track', 'ViewContent', {
        content_name: 'Customer Satisfaction Survey',
        campaign: 'Q1-2024'
      });
    </script>
    ```
  </Step>

<Step title="Save Changes">
    Click **Save** to apply the survey-specific scripts.
  </Step>
</Steps>

## To keep in mind

<Warning>
  Custom scripts execute in the context of your survey pages. Only add scripts from trusted sources. Malicious scripts could compromise your survey data or user privacy.
</Warning>

* **Scripts Don't Load in Preview Mode** — Custom Head Scripts are not loaded in preview mode (editor preview or `?preview=true`). This prevents analytics tracking and pixel triggers during testing. To test your scripts, publish your survey and view it through the actual link survey URL without the preview parameter.

* **Link Surveys Only** — Custom Head Scripts only work with link surveys. They are not available for app/website surveys, as those are embedded in your application and should use your application's existing script management.

* **Self-Hosted Only** — This feature is only available on self-hosted instances. Formbricks Cloud does not support Custom Head Scripts for security and performance reasons.

* **Permissions** — Only Owners, Managers, and members with Manage access can configure Custom Head Scripts.

## Common Use Cases

### Global Analytics (Workspace Level)

Set up Google Analytics for all surveys in your workspace:

```html theme={null}
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>
```

### Campaign-Specific Tracking (Survey Level with Add Mode)

Add Facebook Pixel tracking for a specific marketing campaign:

**Workspace Scripts:** Google Analytics (as above)

**Survey Scripts:**

```html theme={null}
<script>
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>
```

**Result:** Both Google Analytics and Facebook Pixel run on this survey.

### Custom Fonts (Workspace Level)

Load custom fonts for all your surveys:

```html theme={null}
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
  body {
    font-family: 'Inter', sans-serif;
  }
</style>
```

## Troubleshooting

If your scripts aren't loading, check:

1. **Is it a self-hosted instance?** Custom scripts only work on self-hosted Formbricks.
2. **Are you in preview mode?** Scripts don't load in preview—test with the actual survey link.
3. **Check the browser console** for JavaScript errors that might prevent script execution.
4. **Verify your HTML syntax** is correct (properly closed tags, valid attributes).

# Data Prefilling
Source: https://formbricks.com/docs/surveys/link-surveys/data-prefilling

URL Data Prefilling for Link Surveys in Formbricks

Data prefilling via the URL allows you to increase completion rate by prefilling data you already have in a different system. Formbricks allows you to prefill multiple questions in a survey and skip prefilled questions.

## Purpose

Data prefilling via URL comes in handy when you:

* Have data for some of the respondents, but not all
* Have data you want the respondent to confirm or update
* Have data in a different system (e.g. your database) and want to add it to the user profile in Formbricks
* Want to embed a survey in an email and increase completion by prefilling the choice selected in the email

## Quick Example

```sh Example URL theme={null}
https://app.formbricks.com/s/clin3dxja02k8l80hpwmx4bjy?question_id_1=answer_1&question_id_2=answer_2&skipPrefilled=true
```

## How it works

1. To prefill survey questions, add query parameters to the survey URL using the format `questionId=answer`.
2. The answer must match the question’s expected type to pass [validation](/docs/surveys/link-surveys/data-prefilling#validation). For Single Select and Multi Select questions, `answer` can be either the option label text or the option ID.
3. The answer needs to be [URL encoded](https://www.urlencoder.org/) (if it contains spaces or special characters)

### Skip prefilled questions

You can skip prefilled questions by adding the `skipPrefilled` parameter in the URL. To skip prefilled questions and show the next available question, add `skipPrefilled=true` to the URL. By default, `skipPrefilled` is set to `false`.

```sh Skipping prefilled questions theme={null}
app.formbricks.com/s/clin3dxj?question_id_1=answer_1&skipPrefilled=true
```

### Prefilling multiple values

Formbricks lets you prefill as many values as you want. Combine multiple values in the URL using `&`, for example: `name=Bernadette&age=18`. The order of query parameters doesn’t matter, so you can move questions around or add new ones without worrying about the parameter order.

### Where do I find my question Id?

You can find the `questionId` in the **Advanced Settings** at the bottom of each question card in the Survey Editor. You can update the `questionId` to any string you like **before you publish a survey.** After you published a survey, you cannot change the id anymore.

## Examples

Here are a few examples to get you started:

### Rating Question

Translates to 5 stars / points / emojis:

```sh Rating Question theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?rating_question_id=5
```

### NPS Question

Translates to an NPS rating of 10:

```sh NPS Questions theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?nps_question_id=10
```

### Single Select Question (Radio)

Chooses the option 'Very disappointed' in the single select question. The string has to be identical to the option in your question:

```sh Single-select Question theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?single_select_question_id=Very%20disappointed
```

### Multi Select Question (Checkbox)

Selects three options 'Sun, Palms and Beach' in the multi select question. The strings have to be identical to the options in your question:

```sh Multi-select Question theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?multi_select_question_id=Sun%2CPalms%2CBeach
```

### Open Text Question

Adds 'I love Formbricks' as the answer to the open text question:

```sh Open Text Question theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?openText_question_id=I%20love%20Formbricks
```

### Consent Question

Adds 'accepted' as the answer to the Consent question. Alternatively, you can set it to 'dismissed' to skip the question.

```txt Consent Question theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?consent_question_id=accepted
```

### Picture Selection Question

Adds index of the selected image(s) as the answer to the Picture Selection question. The index starts from 1

```txt Picture Selection Question theme={null}
https://app.formbricks.com/s/clin3yxja52k8l80hpwmx4bjy?pictureSelection_question_id=1%2C2%2C3
```

## Using Option IDs for Single Select and Multi Select Questions

Single Select and Multi Select questions support prefilling with **option IDs** in addition to option labels. This is the most robust approach and the recommended default, especially for multilingual surveys.

### Why Option IDs are recommended

* **Stable:** Option IDs don't change when you edit option labels.
* **Language-independent:** The same URL works across all survey languages.
* **Reliable:** No brittle string matching and fewer URL-encoding issues.

### One link per option

When you create one CTA link per answer option (for example in emails), use the option ID as the parameter value:

```sh Option-ID prefill theme={null}
https://app.formbricks.com/s/cmoh0584taxoxu501jyvk8tzn?tuk2i9ktui1lee0mfos82czb=e2r697fou23n7ba4vmt7you6
```

In this example:

* `tuk2i9ktui1lee0mfos82czb` is the question ID.
* `e2r697fou23n7ba4vmt7you6` is the selected option ID.

### How to Find Option IDs

1. Open your survey in the Survey Editor
2. Click on the question you want to prefill
3. Open the **Advanced Settings** at the bottom of the question card
4. Each option shows its unique ID that you can copy

### Examples with Option IDs

**Single Select:**

```sh Single Select with Option ID theme={null}
https://app.formbricks.com/s/surveyId?questionId=option-abc123
```

**Multi Select:**

```sh Multi Select with Option IDs theme={null}
https://app.formbricks.com/s/surveyId?questionId=option-1,option-2,option-3
```

**Mixed IDs and Labels:**

You can even mix option IDs and labels in the same URL (though using IDs consistently is recommended):

```sh Mixed Approach theme={null}
https://app.formbricks.com/s/surveyId?questionId=option-abc,Some%20Label,option-xyz
```

### Backward Compatibility

All existing URLs using option labels continue to work. The system tries to match by option ID first, then falls back to matching by label text if no ID match is found.

## Validation

Make sure that the answer in the URL matches the expected type for the questions.

The URL validation works as follows:

* **Rating or NPS questions:** The response is parsed as a number and verified to be within the valid range.
* **Consent type questions:** Valid values are "accepted" (consent given) and "dismissed" (consent not given).
* **Picture Selection questions:** The response is parsed as comma-separated numbers (1-based indices) and verified against available choices.
* **Single/Multi Select questions:** Values can be either option IDs or exact label text. The system tries option ID matching first, then falls back to label matching.
* **Open Text questions:** Any string value is accepted.

<Note>
  If an answer is invalid or doesn't match any option, the prefilling will be ignored and the question is presented as if not prefilled.
</Note>

# Embed Surveys
Source: https://formbricks.com/docs/surveys/link-surveys/embed-surveys

Embed Formbricks surveys seamlessly into your website using an iframe & Email using code snippets.

# Embed Surveys in Your Web Page & Emails

Embedding Formbricks surveys directly into your web pages & emails allows you to integrate interactive surveys without redirecting users to a separate survey site. This method ensures a seamless integration and maintains the aesthetic continuity of your website or application and your email marketing campaigns.

## Embedding Surveys in Web Pages

1. Create and publish a link survey.

2. Open survey summary page and click on **share** button on the top right.

3. In the survey share modal, click on **Embed survey** button.

4. Navigate to **Embed in a Web Page** tab and click on Copy code

5. Paste the copied iframe code into the HTML of your web page where you want the survey to appear.

### Example of Embedding a Survey on a Web Page

```html Example Embedding Code theme={null}
<div style="position: relative; height:100vh; max-height:100vh; overflow:auto;">
  <iframe
    src="https://app.formbricks.com/s/<your-surveyId>"
    frameborder="0"
    style="position: absolute; left:0; top:0; width:100%; height:100%; border:0;"
  >
  </iframe>
</div>
```

## Iframe Events

The iframe fires a **formbricksSurveyCompleted** event when a user finishes a survey within the embedded iframe. This event can be captured through a message listener in your webpage's JavaScript

### How to Use it?

1. Embed the Formbricks survey on your webpage using the iframe method as described above.

2. Add an event listener to your webpage’s JavaScript that listens for `message` events from the iframe.

3. Check if the received message indicates that the survey is completed by comparing the `event.data` with the value `formbricksSurveyCompleted`.

<Note>
  It is important to verify the origin of the message to ensure it comes from
  the iframe containing your survey, enhancing the security of your event
  handling.
</Note>

4. Implement your custom actions within the callback function based on the survey completion.

### Example of Handling Survey Completion Events

```javascript Example Code for Event Listener theme={null}
window.addEventListener("message", (event) => {
  // Replace 'https://app.formbricks.com' with the actual web app url
  if (
    event.origin === "https://app.formbricks.com" &&
    event.data === "formbricksSurveyCompleted"
  ) {
    console.log("Survey completed!");
    // Implement your custom actions here
  }
});
```

## Embed Mode

Embed your survey with a minimalist design, disregarding padding and background.

### How to enable Embed Mode

It can be enabled by simply appending **?embed=true** to your survey link or from UI

1. Open Website embed tab in survey share modal

2. Toggle **Embed mode**

With Embed mode enabled:

With Embed mode disabled:

## Embedding Surveys in Emails

Embedding Formbricks surveys directly into your emails allows you to collect valuable feedback from your users at every touchpoint. Seamlessly integrate interactive surveys into your email campaigns to gather insights and improve user experience.

## Generate an Embed Code

To embed a Formbricks survey in an email, first, create a survey and publish it. Follow these steps to generate the embed code:

1. **Create and Publish a Survey**: Start by creating a link survey and publish it once ready.
2. **Access the Share Options**: Go to the survey summary page and click the Share button (see below).
3. **Get the Embed Code**: Click on Embed Survey at the bottom of the share modal, navigate to the `Embed in an Email` tab, and click `Copy Code`.
4. **Preview and Test**: Before sending it to your users, click on Send Preview to receive a test email. This helps ensure the survey appears correctly.

## Embedding the Survey in Emails

Different email clients have different support for HTML and CSS. We recommend testing the email in different email clients to ensure the survey looks good in all of them.

Below are some of the methods and services that we know that allows HTML embedding and how you can use them:

<Note>
  Please use the below methods at your own discretion. We do not officially
  endorse any of the services mentioned below.
</Note>

### 1. Gmail

Gmail does not support HTML embedding natively. It's a WYSIWYG (What You See Is What You Get) editor. However, you can use a free plugin like [HTML Editor for Gmail by cloudHQ](https://chromewebstore.google.com/detail/free-html-editor-for-gmai/ioinaaeeacahcmbgfmeaaofhfkijpdeb) to embed HTML in your emails.

* Install the plugin from the Chrome Web Store.

* Open Gmail and compose a new email.

* Write your email content after which you want to embed the survey.

* Right next to the Send button you will see a new button called **HTML Editor**. Click on it.

* This will open a new window with the **Design** tab active. Switch to the **Source** tab.

* Now paste the copied HTML code from Formbricks into this window. On the right, you will see a preview of how the email will look.

* Click on the **Close Editor** button to save the changes & close the editor.

* Voila! You have successfully embedded the survey in your email.

### 2. Sendgrid

Sendgrid supports HTML content in emails directly:

* Compose Your Email: Use Sendgrid's email composition tools to embed the HTML directly into your email body.
* Reference: For detailed steps, refer to Sendgrid's official documentation [here](https://sendgrid.com/en-us/solutions/email-marketing/email-design) or API docs [here](https://sendgrid.com/docs/for-developers/sending-email/api-getting-started/)

### 3. Mailchimp

Available in their Standard plan and above, Mailchimp allows HTML content embedding:

* Use the Code Block: Drag a code block into your email template and paste the HTML code for the survey.
* Reference: Check out Mailchimp's guide on pasting in custom HTML [here](https://mailchimp.com/help/paste-in-html-to-create-an-email/)

### 4. Nodemailer

Nodemailer is a Node.js module that allows you to send emails with HTML content.

* If you use Node.js to send emails, just attach the `html` parameter in your email message.
* Reference: Take a look at Nodemailer's official message documentation [here](https://nodemailer.com/message/)

<Note>
  Please note that the above methods are not exhaustive and there are many other
  ways to embed HTML in emails.
</Note>

## Example: Email Footer Survey

Embed a survey link in your email signature to collect feedback subtly yet effectively. Here’s how:

1. Create a Survey: Adjust an existing survey or create a new one.
2. Scroll down & enable the **Hidden Fields** option.
3. Add a new hidden field with the name **helpful**.
4. Now Publish the survey as a Link Survey & copy the link.
5. Embed in Your Signature: Add this HTML snippet to your email signature in your email client settings.

```html Embed this in your Email theme={null}
Was our conversation helpful?
<a href="<Link-Survey-URL>?helpful=Yes">Yes 👍</a> |
<a href="<Link-Survey-URL>?helpful=No">No 👎</a>
```

Replace `YOUR_SURVEY_LINK` with the actual survey link.

PS: If you do not see any signature settings, just use one of the methods we've mentioned above to embed the HTML code in your email.

***

**Need help?** [Reach out in Github Discussions](https://github.com/formbricks/formbricks/discussions)

# Link Settings
Source: https://formbricks.com/docs/surveys/link-surveys/link-settings

Customize link titles, descriptions, and preview images to make your survey links more engaging when shared on social media and other platforms.

<Note>
  **Self-Hosting Requirements**: Adding a preview image requires file upload storage to be configured. If
  you're self-hosting Formbricks, make sure to [configure file
  uploads](/docs/self-hosting/configuration/file-uploads) before using this feature.
</Note>

## What are Link Settings?

Link Settings allow you to configure the metadata (Open Graph tags) for your survey links, controlling how they appear when shared:

* **Link Title**: The headline that appears when your link is shared
* **Link Description**: A brief description of your survey
* **Preview Image**: A custom image that displays alongside your link preview

## Configuring Link Metadata

<Steps>
  <Step title="Access Link Settings">
    Navigate to your survey's Summary page and click the **Share survey** button in the top toolbar.
  </Step>

<Step title="Open Link Settings tab">
    In the Share Modal, click on the **Link Settings** tab to access the customization options.
  </Step>

<Step title="Customize your link title">
    Enter a title for your survey link. This will appear as the main headline when your link is shared.
  </Step>

<Step title="Add a link description">
    Write a brief description for your survey. This will appear as the description of your Survey Link.
  </Step>

<Step title="Upload a preview image">
    Add a custom image that will display when your link is shared. This makes your survey more visually
    appealing and can increase engagement.
  </Step>

<Step title="Save your settings">
    Click **Save** to apply your link settings. These changes will take effect immediately for all future link shares.
  </Step>
</Steps>

# Market Research Panel with Prolific
Source: https://formbricks.com/docs/surveys/link-surveys/market-research-panel

Formbricks surveys can be integrated with Prolifics participant panel easily. This tutorial walks you through the steps on how to access a pool of over 200.000 participants for your research.

<Note>
  Prolific is a paid service. You need to fund your account to access the pool
  of participants. The cost depends on the number of participants you want to
  reach and the demographics you're targeting. You can get an estimate of the
  cost with the [Prolific price calculator](https://www.prolific.com/calculator)
</Note>

## Purpose

External research panels are useful when:

* You don't have access to enough people who match your target audience
* You want to reach a specific demographic
* You want to reach a large number of people quickly

## Steps to Follow

### Step 1: Add hidden fields to the Formbricks survey

To be able to attribute a completed answer to a research participant, you need to add hidden fields to your Formbricks survey. To do so, edit your survey and scroll down to the Hidden Fields card.

Add three fields with the IDs `PROLIFIC_PID`, `STUDY_ID`, and `SESSION_ID`.

### Step 2: Create an account on Prolific

Go to [Prolific](https://app.prolific.co/) and create an account.

### Step 3: Create a study on Prolific

Once you're logged in to Prolific, create a new study.

### Step 4: Copy the Formbricks survey link to the Prolific study

We connect the Formbricks survey with the Prolific study by copying the survey link from Formbricks and pasting it into the Prolific study:

### Step 5: Choose URL parameters for attribution

To attribute responses to the correct participant, you need to add URL parameters to the Formbricks survey link. The parameters are `PROLIFIC_PID`, `STUDY_ID`, and `SESSION_ID`, exactly like the hidden fields you added.

### Step 6: Update the Formbricks Redirect URL

To ensure that participants are redirected back to Prolific after completing the survey, add the redirect URL provided in the Prolific study setup (e.g. `https://app.prolific.co/submissions/complete?cc=I2PWSFRG`)

Copy from Prolific:

Set it up as Redirect URL in the Response Options in Formbricks:

### Step 7: Preview the study

Preview the study using Prolific's [Preview-functionality](https://researcher-help.prolific.com/hc/en-gb/articles/360009222853-Previewing-your-study)

Got to the success screen? Then you're ready to publish your study!

### Step 8: Publish the study

After you've published the study, you'll get the first responses within a few hours.

<Note>
  Prolific is a paid service. You need to fund your account to publish your
  study.
</Note>

### That's it! 🎉

Once you've published the survey, you can sit back and watch the responses come in. Prolific will take care of the rest.

# Offline Support
Source: https://formbricks.com/docs/surveys/link-surveys/offline-support

Allow respondents to complete link surveys even without an internet connection.

Offline support lets respondents fill out link surveys when they lose connectivity. Responses are stored locally on the device and automatically synced to the server when the connection is restored.

## How it Works

1. When enabled, survey responses are saved to the browser's IndexedDB as the respondent progresses.
2. If the respondent goes offline, they can continue filling out the survey without interruption.
3. When the connection is restored, all pending responses are automatically synced to the server.
4. A status alert is shown at the top of the page to inform the respondent of the current state (offline, syncing, or synced).

<Note>
  Offline support is only available for **link surveys**. App and website surveys are not affected.
</Note>

## Enabling Offline Support

Append the `offlineSupport=true` query parameter to your survey link:

```sh theme={null}
https://formbricks.com/s/your-survey-id?offlineSupport=true
```

You can combine it with other query parameters:

```sh theme={null}
https://formbricks.com/s/your-survey-id?offlineSupport=true&source=Google&lang=de
```

## Limitations

* **File uploads** are not supported offline. Text, choice, number, and other non-file responses are fully queued.
* **Stale data** is automatically discarded after 24 hours if it was never synced.
* The alert banner is not shown when the survey is embedded via iframe (`isEmbed` mode).

# Personal Links
Source: https://formbricks.com/docs/surveys/link-surveys/personal-links

Personal Links enable you to generate unique survey links for individual contacts, allowing you to attribute responses directly to specific people and set expiry dates for better control over survey distribution.

<Note>
  Personal Links are part of the [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

## When to use Personal Links

Personal Links are ideal when you need to:

* **Track individual responses**: Associate survey responses with specific contacts in your database
* **Enable targeted follow-ups**: Know exactly who responded and who didn't for personalized outreach
* **Control survey access**: Set expiry dates to limit when links can be used
* **Maintain data integrity**: Ensure each contact can only submit one response per survey

## How Personal Links work

When you generate personal links:

1. **Individual URLs**: Each contact receives a unique survey link tied to their contact record
2. **Automatic attribution**: Responses are automatically linked to the specific contact who clicked the link
3. **Single-use by default**: Each link can only be used once to prevent duplicate responses
4. **Expiry control**: Set expiration dates to control survey access windows

## Generating Personal Links (UI)

<Steps>
  <Step title="Access the share modal">
    Navigate to your survey summary page and click the **Share survey** button in the top bar.
  </Step>

<Step title="Select Personal Links tab">
    In the Share Modal, click on the **Personal Links** tab.
  </Step>

<Step title="Choose your segment">
    Select the contact segment you want to generate links for using the dropdown menu.

<Note>
      If no segments are available, you'll see "No segments available" in the dropdown. Create segments first in your Contact Management section.
    </Note>
  </Step>

<Step title="Set expiry date (optional)">
    Choose an expiry date for your links. You can only select dates starting from tomorrow onwards.

<Warning>
      Links expire at 00:00:00 UTC on the day after your selected date. This means links remain valid through the entirety of your chosen expiry date.
    </Warning>
  </Step>

<Step title="Generate and download">
    Click **Generate & download links** to create your personal links and download them as a CSV file.
  </Step>
</Steps>

### Understanding the CSV export

Your downloaded CSV file contains the following columns in this order:

| Column                    | Description                               |
| ------------------------- | ----------------------------------------- |
| **Formbricks Contact ID** | Internal contact identifier (`contactId`) |
| **Custom ID**             | Your custom user identifier (`userId`)    |
| **First Name**            | Contact's first name                      |
| **Last Name**             | Contact's last name                       |
| **Email**                 | Contact's email address                   |
| **Personal Link**         | Unique survey URL for this contact        |

<Tip>
  Use the Custom ID column to match contacts with your existing systems, and the Personal Link column for distribution via your preferred communication channels.
</Tip>

## Generating Personal Links (API)

We also offer a way to generate Personal Links via the API. You can use two endpoints for generating Personal Links: For [individual contacts](/docs/api-v2-reference/management-api--surveys--contact-links/get-personalized-survey-link-for-a-contact) and for a [whole segment](/docs/api-v2-reference/management-api--surveys--contact-links/get-survey-links-for-contacts-in-a-segment).

## Limitations and considerations

<Warning>
  Keep these limitations in mind when using Personal Links
</Warning>

* **Single-use only**: Each personal link can only be used once
* **Enterprise feature**: Requires EE license with Contact Management enabled
* **Segment requirement**: You must have contacts organized in segments
* **CSV storage**: Generated link lists are not retained in Formbricks - download and store your CSV files securely

## Troubleshooting

<Tabs>
  <Tab title="No segments available">
    **Issue**: Dropdown shows "No segments available"

**Solution**: Create contact segments in your Contact Management section before generating personal links.
  </Tab>

<Tab title="Generation failed">
    **Issue**: "Something went wrong" error message

**Solution**:

* Check your internet connection
    * Verify you have sufficient contacts in the selected segment
    * Contact support if the issue persists
  </Tab>

<Tab title="Links not working">
    **Issue**: Personal links lead to error pages

**Solution**:

* Verify the link hasn't expired
    * Check that the survey is still published
    * Ensure the link hasn't been used already (single-use limitation)
  </Tab>
</Tabs>

# PIN Protected Surveys
Source: https://formbricks.com/docs/surveys/link-surveys/pin-protected-surveys

Enhance the security and exclusivity of your surveys by requiring respondents to enter a secure 4 digit PIN to access your survey. Learn how to enable PIN protection and the benefits it offers.

## **Enabling PIN Protection**

PIN protection can be applied to your surveys easily through the survey editor. This setup allows you to control access effectively, ensuring that only authorized users can participate.

### **Steps to Set Up PIN Protection**

1. **Open Settings in Survey Editor**: Navigate to your survey in the survey editor where you wish to enable PIN protection & click on Settings Tab.

2. **Select Response Options**: Find and select **`Response Options`** to access settings related to survey responses.

3. **Enable PIN Protection**: Find the option for "Protect Survey with a PIN" and
   activate it. You will be prompted to enter a PIN that respondents must use to access
   the survey.

### **Setting the PIN**

Enter the PIN you wish to use for your survey. Once set, this PIN will need to be
entered by participants to access the survey. Note that this can be changed anytime
from here in the future.

### **User Experience Upon Accessing the Survey**

When a respondent attempts to access the survey, they are prompted to enter the PIN:

* **PIN Entry Prompt**: A screen will appear asking the respondent to enter the PIN to proceed. This acts as the first gatekeeping step before survey access is granted.

* **Incorrect PIN Handling**: If an incorrect PIN is entered, the respondent will be informed and asked to try again, ensuring secure access to the survey.

* **Correct PIN**: On entering the correct PIN, the user access the survey & can fill it accordingly.

### **Benefits of PIN Protection**

* **Enhanced Security**: Protects the survey from unauthorized access, ensuring that only participants with the PIN can enter.

* **Controlled Participation**: Enables you to restrict survey participation to a specific group, such as during a closed testing phase or confidential feedback gathering.

* **Prevents Unwanted Access**: Deters casual browsing and unauthorized attempts to view or complete the survey.

## **Use Cases**

PIN protection is particularly useful in situations where:

* Confidential surveys are being conducted, such as internal company feedback or sensitive research studies.

* Surveys are designed for a specific event or group, and access needs to be controlled.

* You want to limit survey responses to participants who have been explicitly invited or have registered in advance.

## **Conclusion**

Setting up PIN protection for your Formbricks surveys is a straightforward and effective way to ensure that only authorized respondents can access and complete your surveys. This feature adds an additional layer of security and control, making it ideal for managing access to sensitive or exclusive surveys.

# Pretty URL
Source: https://formbricks.com/docs/surveys/link-surveys/pretty-url

Create a custom, memorable URL for your survey instead of sharing a long auto-generated link.

<Note>
  **Self-Hosted Only**: Pretty URLs are available exclusively on self-hosted Formbricks instances. This feature is not available on Formbricks Cloud.
</Note>

## What is a Pretty URL?

By default, every survey is accessible at a URL containing its auto-generated ID, e.g. `yourdomain.com/s/cm1abc123xyz`. A Pretty URL lets you replace that with a short, human-readable slug of your choice:

```
yourdomain.com/p/customer-feedback
```

When someone visits the pretty URL, they are automatically redirected to the actual survey. Query parameters such as `suId` and `lang` are forwarded as well.

## Setting Up a Pretty URL

<Steps>
  <Step title="Open the Share Modal">
    Navigate to your survey's **Summary** page and click the **Share survey** button in the top toolbar.
  </Step>

<Step title="Go to the Pretty URL tab">
    In the Share Modal, select the **Pretty URL** tab.
  </Step>

<Step title="Enter a slug">
    Type your desired slug in the input field. Slugs may only contain **lowercase letters, numbers, and hyphens** (e.g. `customer-feedback`, `q4-nps-2024`).

The full URL is shown in real time below the input so you can confirm how it will look.
  </Step>

<Step title="Save">
    Click **Save**. The slug is now live. Anyone visiting the pretty URL is immediately redirected to your survey.
  </Step>
</Steps>

## Managing Pretty URLs

Once a slug is saved, the Pretty URL tab shows the active link with two actions:

* **Copy**: copies the full pretty URL to your clipboard.
* **Remove**: deletes the slug (after a confirmation prompt). The survey remains accessible via its original `/s/[surveyId]` URL.

## Viewing All Pretty URLs in Your Organization

All surveys that have a pretty URL assigned are listed in one place:

1. Go to **Settings → Organization → Domain**.
2. Open the **Pretty URLs** section.

The table shows each survey's name, workspace, slug, and environment type (production / development).

## Slug Rules

| Rule           | Detail                                                 |
| -------------- | ------------------------------------------------------ |
| Characters     | Lowercase letters (a-z), digits (0-9), and hyphens (-) |
| Uniqueness     | Must be unique across your entire Formbricks instance  |
| Format example | `customer-feedback`, `onboarding-survey`, `q4-nps`     |

## Query Parameter Forwarding

Pretty URLs forward all query parameters to the destination survey URL. For example:

```
/p/customer-feedback?suId=contact123&lang=de
```

redirects to:

```
/s/[surveyId]?suId=contact123&lang=de
```

This means features like [single-use links](/docs/surveys/link-surveys/single-use-links), [data prefilling](/docs/surveys/link-surveys/data-prefilling), and [multi-language surveys](/docs/surveys/general-features/multi-language-surveys) all work with pretty URLs.

# Quickstart - Link Surveys
Source: https://formbricks.com/docs/surveys/link-surveys/quickstart

Create your first link survey in under 5 minutes.

Link Surveys make it easy for your users to give you feedback. They are a great way to get feedback from your users, without interrupting their workflow. This quickstart guide will show you how to create your first link survey in under 5 minutes.

<Steps>
  <Step title="Create a free Formbricks Cloud account">
    While you can [self-host](/docs/self-hosting/overview) Formbricks, the quickest and easiest way to get started is with the free Cloud plan. Just [sign up here](https://app.formbricks.com/auth/signup) and click through the onboarding.
  </Step>

<Step title="Choose a template">
    In your workspace, click **New Survey** and pick **Choose a template**. We'll use the **Product Market Fit (Superhuman)** template for this quickstart guide.

Click the template to preview it, then hit **Use this template**.

<Step title="Create your first survey">
    You'll be taken to the survey editor. The **Questions** tab holds the blocks and questions that came with the template, and the preview on the right updates as you edit. To keep it simple, we'll leave the questions as they are.

<Step title="Set the survey type to Link Survey">
    Open the **Settings** tab and choose **Link Survey** under **Survey Type**. This is what gives your survey a shareable URL, instead of running it inside your app or website.

<Step title="Configure your survey settings">
    Still in the **Settings** tab, open **Response Options**. Formbricks packs a lot of useful functionality out of the box. You can:

* Close the survey on a specific date
    * Close the survey after a number of responses
    * Redirect users to a URL after they completed the survey
    * Protect the survey with a PIN
    * ... and much more!

<Step title="Style your survey">
    Switch to the **Styling** tab and turn on **Add custom styles** to override your workspace theme for this survey. You can keep it simplistic or use animated backgrounds, and you can change the colors, the card layout and the logo.

<Note>
      Want the same look across all of your surveys? Set your theme once in the Look & Feel settings instead. See [Styling Theme](/docs/platform/features/styling-theme).
    </Note>
  </Step>

<Step title="Publish your survey">
    Once you're happy with your survey settings, hit the **Publish** button. You'll be forwarded to the Summary Page where all the responses to your survey will appear.

<Step title="Share your survey">
    Congratulations! Your survey is now published and ready to be shared with your users. Click **Share survey** to copy the survey link, or pick one of the other channels: a website or email embed, social media, a QR code or a dynamic pop-up.

# Single-Use Links
Source: https://formbricks.com/docs/surveys/link-surveys/single-use-links

Make sure that each respondent only replies once with single use links.

This guide will help you understand how to generate and use single-use links within our application.

## Purpose

* Single-use links (or one-time / disposable links) are URLs that grant access to a survey only once.

* The primary purpose of single-use links is to assure that no respondent submits a survey twice.

<Note>
  Want to create up to 5,000 single-use links? Use our [API endpoint for
  that.](https://documenter.getpostman.com/view/11026000/2sA3Bq5XEh#c49ef758-a78a-4ef4-a282-262621151f08)
</Note>

## How to use single-use links

Using single-use links with Formbricks is quite straight-forward:

1. On the Summary page, hit "Share survey" in the top right corner to open the sharing modal.

2. Toggle "Single Use Link" on in the Anonymous Links tab:

3. If you'd like to use URL encryption, toggle "URL Encryption" on. You can then customize the number of links you'd like to generate and download as CSV.

4. If you'd like to set a custom single-use ID, deactivate the "Enable URL Encryption" toggle. You can then customize the single-use ID in the URL or programmatically.

## Check suId of a submission

You can find the suId of each submission in the submission meta data. You'll find it both in the table as well as in the meta data when hovering over the Avatar:

# Source Tracking
Source: https://formbricks.com/docs/surveys/link-surveys/source-tracking

Track the source of your users in an easy & compliant way!

Understand the source a survey respondent comes from when responding to your survey – all while keeping data privacy standards high!

## Purpose

Source tracking for link surveys is essential when you:

* Want to analyze the origin of your survey respondents.
* Aim to ensure compliance with tracking and data collection regulations.

## Code Example

```sh Example Source as Google theme={null}
https://formbricks.com/s/clin3dxja02k8l80hpwmx4bjy?source=Google
```

## How it Works

To track the source of users in your link surveys effectively, follow these steps:

1. **Generate Survey URL**: Create a Link Survey and get the sharable link. Append `?source=YourSouce` to the link to reference it with your campaigns and sources.

```sh Example Source as Google theme={null}
https://formbricks.com/s/clin3dxja02k8l80hpwmx4bjy?source=Google
```

2. **Collect Data**: When users access the survey through these links, the URL parameters will capture the source information from which they were shared.

3. **View Responses**: Use the collected source data to analyze where your survey respondents are coming from. You can hover over the user icon in the responses tab to see the source of the user.

4. **Analyse Data**: Download all the responses as a CSV/Excel and get access to the source information. This can provide valuable insights into your audience.

Source tracking allows you to make informed decisions based on the origin of your survey participants, helping you tailor your surveys and marketing strategies accordingly.

# Start At Specific Block
Source: https://formbricks.com/docs/surveys/link-surveys/start-at-block

Start a survey at a specific block using the URL to skip earlier blocks.

The `startAt` URL parameter lets you open a Link Survey at a specific **block** instead of from the beginning. This is useful when you want to link to a specific part of the survey from external sources or reuse the same survey at different points in the user journey.

## How it works

The survey navigation is block-based: each block can contain one or more questions. When you pass `startAt` with a Question ID, the survey finds the **block** that contains that question and opens at that block. All questions in that block are shown together.

<Note>
  **Multi-question blocks:** When a block has multiple questions, `startAt` opens at the block—you will see all questions in that block, not only the question whose ID you used. For precise "start at this exact question" behavior, use one question per block.
</Note>

## How to use it

1. In the Survey Editor, open the Questions Tab and ensure the survey is set as a **Link Survey**.

2. Find the question (or block) you want to start at, click on **Show Advanced Settings**, and copy the **Question ID** of any question in that block.

<Note>
  Each question has a unique Question ID. Since `startAt` resolves to the block containing the question, you can use any question ID from the target block—typically the first question in that block.
</Note>

3. Append `?startAt=question_id` to your survey's URL, replacing `question_id` with the copied Question ID.

4. Share this modified URL with your users to start the survey at the specified block.

### Sample Link Survey URL with `startAt`

```sh Example Link Survey URL with startAt configured theme={null}
https://formbricks.com/clny997dj087ho30fdzyf4nkl?startAt=bqd29m94l9k0hnc3azbrexl8
```

## Use cases

* **Link to a specific block from an external source:** Direct users to a specific block in your survey from emails, chatbots, or web pages.
* **Use the same survey in different parts of the user journey:** Reuse the survey at different stages, starting at different blocks to gather insights.
* **Create a personalized survey experience:** Tailor the survey by starting at a particular block based on the user's past interactions or preferences.

# Verify Email
Source: https://formbricks.com/docs/surveys/link-surveys/verify-email-before-survey

Verify email before accessing surveys

To ensure the credibility of your survey participants and maintain high-quality data, you can require respondents to verify their email before they can view and respond to your Formbricks link surveys. This verification process helps confirm that only participants with valid email addresses can access the survey, enhancing data integrity.

## **Enabling Email Verification**

This feature, designed for link surveys, can be enabled or disabled directly from the survey editor. Here’s how to activate it:

### **Steps to Enable Email Verification**

1. **Open Survey Editor**: Navigate to your link survey in the survey editor where you wish to enable email verification.

2. **Access Settings**: Click on the **`Settings`** tab next to the Questions & Styling tab.

3. **Select Response Options**: Find and select **`Response Options`** to access settings related to survey responses.

4. **Activate Email Verification**: Find the "Verify Email Before Accessing Survey" option and use the toggle to activate email verification. Specify what details should be visible to the public when they access the survey.

### **User Experience Upon Accessing the Survey**

When email verification is enabled, the following process unfolds for the user:

1. **Email Entry Prompt**: Upon accessing the survey link, the user is prompted to verify their email before they can proceed.

2. **Preview Option**: A "Preview survey questions" option is available for those who are just browsing or curious about the survey content without completing it. This allows a non-interactive view of the survey.

3. **Verification Process**: After entering their email, respondents receive an email containing a survey link, which they can use to access the survey.

4. **Survey Access**: After verifying their email, respondents can access and respond to the survey.

### **Benefits of Email Verification**

* **Authenticity of Respondents**: Ensures that each respondent is verified, adding an extra layer of authenticity to your data collection.
* **Reduction in Spam and Fraudulent Responses**: Helps reduce unwanted or spam entries by confirming the legitimacy of each respondent’s email address.
* **Enhanced Data Quality**: Increases the reliability and quality of the data collected by confirming the identity of participants.

### **Visibility of Verified Emails**

In the Formbricks dashboard, the survey response card displays the verified email along with the responses attached to it, ensuring traceability and authenticity of the data collected.

## **Use Cases**

Email verification is particularly beneficial in scenarios where:

* Market research requires verified responses from specific demographics.
* Surveys are intended for a selected audience with gated content.
* Academic or professional studies necessitate authenticated data for accuracy.

## **Conclusion**

Implementing the Email Verification feature is an effective strategy to ensure the authenticity of your survey respondents. By requiring email verification before survey access, you safeguard the integrity of your survey data and ensure that only verified individuals can contribute responses.

# Surveys
Source: https://formbricks.com/docs/surveys/overview

Design, distribute, and analyze surveys with Formbricks.

Formbricks surveys let you collect feedback from customers, users, and employees through link surveys, website surveys, and in-app surveys.

## Build

A drag-and-drop builder with conditional logic, recall, variables, hidden fields, multi-language support, and over a dozen question types. Surveys can be fully styled to match your brand.

## Distribute

Share surveys via a public link, embed them in your website, or trigger them in your web or mobile app. Use targeting, recontact rules, and quotas to control who sees a survey and when.

## Analyze

Each survey has a built-in summary view and response table. For cross-survey analytics, pipe responses into [Dashboards & Charts](/docs/unify-feedback/dashboards-charts) to build custom visualizations and KPIs. Export to CSV/XLSX, or stream responses out via webhooks and the REST API.

## Next steps

<CardGroup>
  <Card title="Link Surveys" icon="link" href="/surveys/link-surveys/quickstart">
    Share standalone survey links by email, chat, or QR code.
  </Card>

<Card title="Website & App Surveys" icon="mobile" href="/surveys/website-app-surveys/quickstart">
    Trigger surveys inside your website or app.
  </Card>

<Card title="Question Types" icon="question" href="/surveys/question-type/free-text">
    Browse every available question type.
  </Card>

<Card title="Best Practices" icon="lightbulb" href="/surveys/best-practices/understanding-survey-types">
    Templates and proven survey patterns.
  </Card>
</CardGroup>

# Address
Source: https://formbricks.com/docs/surveys/question-type/address

The Address question type allows respondents to input their address details, including multiple fields such as address lines, city, state, and country. You can configure the question by adding a title, an optional description, and toggling specific fields to be required.

## Elements

### Question

Provide a question to describe the address information you are requesting.

### Description

Optionally, add a description to guide the user.

### Toggle Fields

You can choose to show and require any or all of the following fields in the form:

* Address Line 1
* Address Line 2
* City
* State
* Zip Code
* Country

# Consent
Source: https://formbricks.com/docs/surveys/question-type/consent

The Consent card is used to obtain user agreement regarding a product, service, or policy. It features a bold statement or question as the title, followed by a brief description. At the end of the card, users can confirm their consent by checking a checkbox to indicate their agreement.

## Elements

### Title

A bold statement or question asking for user consent, displayed prominently at the top of the card.

### Description

A short explanation or additional context for the consent request, displayed below the title. The text can be formatted, and hyperlinks are allowed within the description.

### Checkbox

At the bottom of the card, users can confirm their agreement by checking the box, indicating their consent to the question or statement above. The label for the checkbox is also editable.

# Contact Info
Source: https://formbricks.com/docs/surveys/question-type/contact-info

The Contact Info question type allows respondents to provide their basic contact information such as name, email, and phone number. You can customize the form with a title, an optional description, and control which fields to display and require.

## Elements

### Title

Specify a title to describe the information you're collecting.

### Description

Optionally, add a description to give additional context.

### Toggle Fields

You can choose to show and require any or all of the following fields:

* First Name
* Last Name
* Email
* Phone Number
* Company

# Date
Source: https://formbricks.com/docs/surveys/question-type/date

The Date question type allows respondents to provide a date, such as when they are available or when an event is scheduled. It features a title to guide the respondent on what date to enter, and an optional description to provide further details or context.

## Elements

### Title

Add a clear title to inform the respondent what date you are asking for.

### Description

Provide an optional description with further instructions.

### Date Format

Choose from multiple date formats for the input:

* MM-DD-YYYY
* DD-MM-YYYY
* YYYY-MM-DD

# File Upload
Source: https://formbricks.com/docs/surveys/question-type/file-upload

The File Upload question type allows respondents to upload files related to your survey, such as production documents or requirement specifications. It features a title to guide the user on what to upload and an optional description to provide additional context.

<Note>
  **Self-Hosting Requirements**: This question type requires file upload storage to be configured. If you're
  self-hosting Formbricks, make sure to [configure file uploads](/docs/self-hosting/configuration/file-uploads)
  before using this feature.
</Note>

## Elements

### Title

Add a clear title that informs the respondent about the purpose of the file upload.

### Description

Provide an optional description to give respondents more details or instructions about what files they need to upload.

### Allow Multiple Files

Enable this option to allow respondents to upload multiple files at once.

### Max File Size

You can set a maximum file size limit, and an input box will appear to specify the size in MB.

### File Type Restrictions

You can restrict the allowed file types. An input box will appear where you can specify the file formats, such as `.pdf`, `.jpg`, `.docx`, etc.

# Free Text
Source: https://formbricks.com/docs/surveys/question-type/free-text

Free text questions allow respondents to enter a custom answer.

Free text questions allow respondents to enter a custom answer. Displays a title and an input field for the respondent to type in.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Placeholder

Specify a placeholder text to display in the input field.

### Input Type

Choose the type of input field to display. Options include:

* **Text**: A text area input. This can be converted to a single line input field if needed, by toggling the *"Long answer"* switch at the bottom of the question segment.
* **Email**: A single-line text input that validates the input as an email address.
* **URL**: A single-line text input that validates the input as a URL.
* **Number**: A single-line text input that validates the input as a number and shows "increase" and "decrease" buttons.
* **Phone**: A single-line text input that validates the input as a phone number.

# Matrix
Source: https://formbricks.com/docs/surveys/question-type/matrix

Matrix questions allow respondents to select a value for each option presented in rows.

The values range from 0 to a user-defined maximum (e.g., 0 to X). The selection is made using radio buttons, and users can choose any value within the defined range, including 0.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Rows

Define the options shown on the left side of the matrix. These represent the items for which users will select a value.

### Columns

Represent the range of values from 0 to X (right side of the screen). Users can choose any value, including 0, using radio buttons.

### Select ordering

* Keep current order: This will keep the order of options the same for all respondents.
* Randomize all: This will randomize the options for each respondent.

# Net Promoter Score
Source: https://formbricks.com/docs/surveys/question-type/net-promoter-score

Net Promoter Score questions allow respondents to rate a question on a scale from 0 to 10. Displays a title and a list of radio buttons for the respondent to choose from.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Labels

Add labels for the lower and upper bounds of the score. The default is "Not at all likely" and "Extremely likely".

### Add color coding

Add color coding to the score. This will show a color bar above the score.

# Ranking
Source: https://formbricks.com/docs/surveys/question-type/ranking

Ranking questions let respondents select options in order from 1 to the total number of options. As they make their choices, the list is automatically rearranged in numerical order.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Options

You need to add at least two options so that users can rearrange them in numerical order based on their selection.

### Select ordering

* Keep current order: This will keep the order of options the same for all respondents.
* Randomize all: This will randomize the options for each respondent.

# Rating
Source: https://formbricks.com/docs/surveys/question-type/rating

Rating questions allow respondents to rate questions on a scale

Rating questions allow respondents to rate questions on a scale. Displays a title and a rating scale consisting of a number of images and labels for the lower and upper ends of the scale.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Scale

Select the icon to be used for the rating scale. The options include: stars, numbers or smileys. The default is stars.

### Range

Select the range of the rating scale. the options include: 3, 4, 5, 6, 7 or 10. The default is 5.

### Labels

Add labels for the lower and upper bounds of the rating scale. The default is "Not good" and "Very good".

## CSAT Summary

After collecting responses, rating questions display a CSAT (Customer Satisfaction) score with a visual traffic light indicator to help you quickly assess satisfaction levels:

* 🟢 **Green** (> 80%): High satisfaction - your users are very satisfied
* 🟠 **Orange** (55-80%): Moderate satisfaction - there's room for improvement
* 🔴 **Red** (\< 55%): Low satisfaction - immediate attention needed

<Note>The traffic light indicator appears automatically in the survey summary view, giving you instant feedback on user satisfaction without needing to dig into the data.</Note>

### How CSAT is Calculated

The CSAT percentage represents the proportion of respondents who gave a "satisfied" rating. What counts as "satisfied" depends on your selected range:

| Range | Satisfied Ratings   | Examples      |
| ----- | ------------------- | ------------- |
| 3     | Highest rating only | ⭐⭐⭐           |
| 4     | Top 2 ratings       | ⭐⭐⭐ or ⭐⭐⭐⭐   |
| 5     | Top 2 ratings       | ⭐⭐⭐⭐ or ⭐⭐⭐⭐⭐ |
| 6     | Top 2 ratings       | 5 or 6        |
| 7     | Top 2 ratings       | 6 or 7        |
| 10    | Top 3 ratings       | 8, 9, or 10   |

<Note>
  **Pro Tip:** For most use cases, a 5-point scale with star or smiley icons provides the best balance between granularity and user experience. Users find it easy to understand and quick to complete.
</Note>

# Schedule A Meeting
Source: https://formbricks.com/docs/surveys/question-type/schedule-a-meeting

The Schedule A Meeting question type allows respondents to book a meeting by selecting a date and time. It includes a title to guide the respondent, along with an optional description to provide additional context for the meeting setup.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Cal.com Username/Event

Add an input box where users can enter their [`cal.com`](https://cal.com/) username and event URL (e.g., `username/event`).

### Custom Hostname (Optional)

Enable an input box for adding a custom hostname, which is necessary if using a self-hosted instance of [`cal.com`](https://cal.com/docs/self-hosting/installation).

# Multi Select
Source: https://formbricks.com/docs/surveys/question-type/select-multiple

Multi select questions allow respondents to select several answers from a list

Multi select questions allow respondents to select several answers from a list. Displays a title and a list of checkboxes for the respondent to choose from.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Options

Define the options shown in the list. These represent the items for which users will select.

Other than the fact that respondents can select multiple options, multi-select questions are similar to [single-select](/docs/surveys/question-type/select-single) questions.

# Picture Selection
Source: https://formbricks.com/docs/surveys/question-type/select-picture

Picture selection questions allow respondents to select one or more images from a list

<Note>
  **Self-Hosting Requirements**: This question type requires file upload storage to be configured for image
  uploads. If you're self-hosting Formbricks, make sure to [configure file
  uploads](/docs/self-hosting/configuration/file-uploads) before using this feature.
</Note>

Picture selection questions allow respondents to select one or more images from a list. Displays a title and a list of images for the respondent to choose from.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Images

Images can be uploaded via click or drag and drop. At least two images are required. Each image must be 5 MB or less.

### Allow Multi Select

This option allows the user to select more than one image.

# Single Select
Source: https://formbricks.com/docs/surveys/question-type/select-single

Single select questions allow respondents to select one answer from a list

Single select questions allow respondents to select one answer from a list. Displays a title and a list of radio buttons for the respondent to choose from.

## Elements

### Title

Add a clear title to inform the respondent what information you are asking for.

### Description

Provide an optional description with further instructions.

### Options

The list of answers the respondent can choose from.

### Additional Actions

* Add “Other”: Adds an “Other” option to allow respondents to enter a custom answer. This will show two inputs, one for the label text and one for the placeholder.

* Convert to Multiple Select: Converts the question to a multiple select question. This will show checkboxes instead of radio buttons.

* Order dropdown: Allows you to choose the order in which the options are displayed.
  * Keep current order: Options will be displayed in the order you added them.
  * Randomize all: Options will be displayed in a random order.
  * Randomize all except last option: Options will be displayed in a random order, except for the last one.

# Statement (Call to Action)
Source: https://formbricks.com/docs/surveys/question-type/statement-cta

The Statement question type allows you to display descriptive information in your survey, such as a message or instruction.

It consists of a title (can be Question or Short Note) and a description, which can be a brief note(realted to CTA) or guideline. Instead of collecting input, this type includes a call to action button for further steps, such as booking an interview call.

## Elements

### Title

This is the main question or heading that appears at the top of the card.

### Description

A brief note or instruction displayed under the title, typically used to provide context or instructions for the next step.

### Button Options

* Button to continue in survey: This will continue respondent with the survey, form or fillups.
* Button to link to external URL: Selecting this option will open-up URL input box below when us set URL the button will redirect to your setted link.

# Actions
Source: https://formbricks.com/docs/surveys/website-app-surveys/actions

Actions are predefined events within your app that prompt Formbricks to display a survey when triggered. These are detected by the Formbricks widget, which then presents the appropriate survey based on your predefined settings.

## How do Actions work?

<Steps>
  <Step title="User performs action">
    The user performs an action in your application.
  </Step>

<Step title="Formbricks widget detects action">
    The embedded widget (SDK) detects the action, if you set up a [No Code
    Action](/docs/surveys/website-app-surveys/actions#setting-up-no-code-actions) or a [Code
    Action](/docs/surveys/website-app-surveys/actions#setting-up-code-actions) to do so.
  </Step>

<Step title="Check for survey trigger">
    If a survey is set to trigger on that action, Formbricks checks if the user or visitor qualifies.
  </Step>

<Step title="Check for user or visitor qualification">
    If the user or visitor already filled out a survey in the past couple of days (see [Workspace-wide Survey Cooldown](/docs/surveys/website-app-surveys/recontact#workspace-wide-survey-cooldown)), the survey will not be shown to prevent survey fatigue.

Also, if this user or visitor has seen this specific survey before, Formbricks might not show it as this is dependent on the [Recontact Options](/docs/surveys/website-app-surveys/recontact).
  </Step>

<Step title="Show survey">
    If all conditions match, the survey is shown.
  </Step>
</Steps>

<Tip>
  Tying surveys to specific user actions enables **context-aware surveying**: You make sure that your user
  research is relevant to the current user context which leads to sign**ificantly higher response and
  completions rates** as well as lower survey fatigue.
</Tip>

<Note>
  **Important**: Any changes to actions, surveys, or environment configuration will take **up to 1 minute** to
  reflect in your app/website due to server-side caching. This includes new actions, modified action
  configurations, and survey trigger updates.
</Note>

## Setting up no-code Actions

Formbricks offers an intuitive No-Code interface that allows you to configure actions without needing to write any code.

<Note>
  No Code Actions are **not available for surveys in mobile apps**. No Code Action tracking are heavily
  dependent on JavaScript and most mobile apps are compiled into a different programming language. To track
  user actions in mobile apps use [Code
  Actions.](/docs/surveys/website-app-surveys/actions#setting-up-code-actions)
</Note>

There are four types of No-Code actions:

### 1. Click action

A Click Action is triggered when a user clicks on a specific element within your application. You can define the element's inner text, CSS selector or both to trigger the survey.

* **Inner Text**: Checks if the innerText of a clicked HTML element, like a button label, matches a specific text. This action allows you to display a survey based on text interactions within your application.

* **CSS Selector**: Verifies if a clicked HTML element matches a provided CSS selector, such as a class, ID, or any other CSS selector used in your website. It enables survey triggers based on element interactions.

* **Both**: Only if both is true, the action is triggered

### 2. Page view action

This action is triggered when a user visits a page within your application.

### 3. Exit intent action

This action is triggered when a user is about to leave your application. It helps capture user feedback before they exit, providing valuable insights into user experiences and potential improvements.

### 4. 50% scroll action

This action is triggered when a user scrolls through 50% of a page within your application. It helps capture user feedback at a specific point in their journey, enabling you to gather insights based on user interactions.

This action is triggered when a user visits a specific page within your application. You can define the URL match conditions as follows:

You can combine the url filters with any of the no-code actions to trigger the survey based on the URL match conditions.

### Page filter

You can limit action tracking to specific subpages of your website or web app by using the Page Filter. Here you can use a variety of URL filter settings:

* **exactMatch**: Triggers the action when the URL exactly matches the specified string.

* **contains**: Activates when the URL contains the specified substring.

* **startsWith**: Fires when the URL starts with the specified string.

* **endsWith**: Executes when the URL ends with the specified string.

* **notMatch**: Triggers when the URL does not match the specified condition.

* **notContains**: Activates when the URL does not contain the specified substring.

* **matchesRegex**: Activates when the URL matches the pattern from the specified string.

## Setting up code Actions

For more granular control, you can implement actions directly in your code:

<Steps>
  <Step title="Configure action in Formbricks">
    First, add the action via the Formbricks web interface to make it available for survey configuration:

<Step title="Add action tracking to your code">
    Use formbricks.track() to send an action event to Formbricks:

```
    formbricks.track("action");
    ```

Here is an example of how to fire an action when a user clicks a button:

```javascript theme={null}
    const handleClick = () => {
      formbricks.track("Button Clicked");
    };

return <button onClick={handleClick}>Click Me</button>;
    ```
  </Step>
</Steps>

# Attribute-based Targeting
Source: https://formbricks.com/docs/surveys/website-app-surveys/attribute-based-targeting

Attribute-based Targeting allows you to show surveys to a specific segment of your users. You can target surveys based on user attributes, device type, and more. This helps you get more relevant insights while keeping survey fatigue at a minimum. After the initial setup, you can target any segment without touching code.

<Note>
  Attribute-based Targeting is part of the [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

### When to use Attribute-based Targeting?

Attribute-based Targeting helps you achieve a number of goals:

1. **Relevance**: Keep survey content relevant to respondents.

2. **Cohort-analysis**: Survey specific user cohorts only.

3. **Statistical Relevance:** When surveying a smaller subset of users, statistical relevance is reached with a lot less responses.

## How does Attribute-based Targeting work?

<Steps>
  <Step title="Create Segment">
    To get started, go to the Contacts tab and create a new Segment:

<Step title="Configure Segment based on attributes">
    In the Segment editor, you can configure your Segment with a combination of Attributes, Segments, Devices, and Survey Interactions. If a user matches either or all of the criteria, they become part of the Segment. See [Segment Configuration](/docs/surveys/website-app-surveys/attribute-based-targeting#segment-configuration) below.
  </Step>

<Step title="Create a survey of type Website & App">
    Create a new survey and go to Settings to change it to Website & App survey:

### Segment Configuration

There are four means to move Contacts in or out of Segments: **Attributes**, other **Segments**, **Devices**, and [**Survey Interactions**](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments):

1. **Attributes**: If the value of a specific attribute matches, the user becomes part of the Segment.

2. **Segments**: You can nest Segments meaning that if a user is or is not part of another Segment, they can be included or excluded

3. **Devices**: If a user uses a Phone or Desktop, you can include or exclude them

4. **Survey Interactions**: Include or exclude Contacts based on whether they have seen, started, or completed a survey within a recent time window. See [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments) for details and use cases like per-survey cooldowns and follow-up funnels.

5. **Filter Groups:** You can group any of the above conditions in group and connect them logically with `AND` or `OR`. This allows for maximum granularity.

# Cooldown Period
Source: https://formbricks.com/docs/surveys/website-app-surveys/cooldown-period

The Cooldown Period is a workspace-wide guard that limits how often a user sees any survey, preventing survey fatigue across all your App Surveys.

The Cooldown Period is a universal blocker that makes sure no user sees too many surveys in a short time. It is measured **across all surveys** in a workspace, which is especially helpful when several teams use Formbricks at the same time. It is one layer of the full display logic — see [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic) for how it combines with targeting, Recontact Options, and triggers.

<Note>The default Cooldown Period is 7 days.</Note>

## Workspace Cooldown Period

To adjust the workspace-wide Cooldown Period:

1. Open **Settings → Workspace → General**.
2. Find the **Cooldown Period (across surveys)** section.
3. Set the interval, in days.

After a user sees *any* survey, no survey will be shown to them again until the Cooldown Period has elapsed.

## Overriding the Cooldown Period for a survey

In the Survey Editor, under **Settings → Visibility & Recontact**, each survey chooses how it interacts with the workspace Cooldown Period:

* **Use Cooldown Period** *(default)* — the survey follows the workspace configuration and only shows if no other survey appeared during that period.
* **Ignore Cooldown Period** — the survey can show whenever its conditions are met, even if another survey was shown recently.
* **Set custom Cooldown Period** — override the workspace value for this survey only.

## How the Cooldown Period is measured

<Warning>
  The Cooldown Period is measured from the last time the user saw **any** survey — not from the last time they saw *this* survey. A per-survey value therefore changes the *length* of the gap, not what resets it: a frequently-shown survey keeps pushing back a less-frequent one.
</Warning>

To run a survey on its **own** schedule regardless of other surveys — for example an NPS survey every 3 months — don't rely on the Cooldown Period alone. Target it with an [interaction-based segment](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments) such as *have not seen this survey within 3 months*, which is evaluated per survey. See [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments) for the full recipe.

***

Still struggling or is something not working as expected? [Join us in GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you!

# Custom CSS
Source: https://formbricks.com/docs/surveys/website-app-surveys/custom-css

Use scoped global CSS to customize Website & App Surveys without breaking your app styles.

Yes, custom CSS for Website & App Surveys is supported.

Use this when the Styling UI is not enough and you need tighter brand control.

<Note>
  Start with the built-in [Styling Theme](/docs/platform/features/styling-theme) first. Use custom CSS only for advanced overrides.
</Note>

## Problem

Website & App Surveys are rendered inside your product, so your app's global CSS can compete with survey styles.

Common examples:

* A global rule like `button { ... !important; }` changes survey buttons.
* Typography resets change survey text spacing and sizing.
* Utility-heavy global styles create unexpected visual differences between pages.

## Solution

Scope your overrides to the survey root (`#fbjs`) and use `!important` for the exact targets you want to control.

This gives you two important guarantees:

1. Your custom rules apply only to the survey.
2. Your rules reliably win against conflicting global styles.

## Add Scoped Overrides In Global CSS

<Steps>
  <Step title="Open your global stylesheet">
    Use the stylesheet that is loaded on pages where surveys are shown (for example `globals.css`).
  </Step>

<Step title="Add scoped rules under #fbjs">
    Keep all custom rules prefixed with `#fbjs`.
  </Step>

<Step title="Use !important only where needed">
    Add `!important` to properties that are still being overridden by your app-wide CSS.
  </Step>
</Steps>

```css globals.css theme={null}
/* 1) Theme-level variables */
#fbjs {
  --fb-brand-color: #0ea5e9 !important;
  --fb-brand-text-color: #ffffff !important;
  --fb-heading-color: #0f172a !important;
  --fb-subheading-color: #334155 !important;
  --fb-survey-background-color: #ffffff !important;
  --fb-border-radius: 12px !important;
}

/* 2) Targeted component overrides */
#fbjs .button-custom,
#fbjs button.button-custom {
  border: 1px solid #0284c7 !important;
  box-shadow: none !important;
}

#fbjs .label-headline,
#fbjs .label-headline * {
  font-size: 1.125rem !important;
  font-weight: 700 !important;
}

#fbjs .bg-input-bg,
#fbjs .border-input-border,
#fbjs .text-input-text {
  background: #f8fafc !important;
  border-color: #cbd5e1 !important;
  color: #0f172a !important;
}
```

<Info>
  Internal Tailwind utility classes are implementation details and may change over time. Prefer CSS variables and stable survey selectors scoped under `#fbjs`.
</Info>

## Best Practices

* Keep all survey overrides in one section or file for easier maintenance.
* Avoid global selectors without `#fbjs` (for example `button`, `input`, `p`) when styling surveys.
* Document why each `!important` exists so future cleanup is easy.
* After changes, hard refresh your page to clear cached SDK assets.

## Troubleshooting

**My app styles still win over survey styles**

* Increase selector specificity under `#fbjs`.
* Add `!important` only on the conflicting property.
* Check the browser inspector to confirm which rule is winning.

**Survey styles are affecting the rest of my app**

* This usually means a selector is missing `#fbjs`.
* Prefix every rule with `#fbjs` to keep styles isolated.

## Survey UI CSS Class Reference

The following classes are used by `packages/survey-ui` and are safe to target when scoped with `#fbjs`.

| CSS class                 | Element(s) it styles                                                                  | Notes                                    |
| ------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |
| `.button-custom`          | Survey action buttons (submit, CTA, navigation buttons with custom variant)           | Applies `--fb-button-*` styling tokens.  |
| `.label-headline`         | Question headlines and headline HTML content                                          | Used by `Label` variant `headline`.      |
| `.label-description`      | Question descriptions and helper copy                                                 | Used by `Label` variant `description`.   |
| `.label-default`          | Default label text content                                                            | Used by `Label` variant `default`.       |
| `.label-card`             | Upper labels (for example, required label text)                                       | Used by `Label` variant `card`.          |
| `.progress-track`         | Progress bar track container                                                          | Uses `--fb-progress-track-*` tokens.     |
| `.progress-indicator`     | Progress bar fill indicator                                                           | Uses `--fb-progress-indicator-*` tokens. |
| `.rounded-input`          | Input-like controls (text inputs, dropdown triggers, date inputs, rating/NPS options) | Controls input border radius token.      |
| `.bg-input-bg`            | Input-like control backgrounds                                                        | Maps to `--fb-input-bg-color`.           |
| `.border-input-border`    | Input-like control borders                                                            | Maps to `--fb-input-border-color`.       |
| `.text-input`             | Input-like text size                                                                  | Maps to `--fb-input-font-size`.          |
| `.text-input-text`        | Input text and some input icons                                                       | Maps to `--fb-input-color`.              |
| `.text-input-placeholder` | Placeholder and empty-state text                                                      | Maps to `--fb-input-placeholder-color`.  |
| `.font-input`             | Input-like font family                                                                | Maps to `--fb-input-font-family`.        |
| `.font-input-weight`      | Input-like font weight                                                                | Maps to `--fb-input-font-weight`.        |
| `.w-input`                | Input width                                                                           | Maps to `--fb-input-width`.              |
| `.min-h-input`            | Input minimum height                                                                  | Maps to `--fb-input-height`.             |
| `.px-input-x`             | Input horizontal padding                                                              | Maps to `--fb-input-padding-x`.          |
| `.py-input-y`             | Input vertical padding                                                                | Maps to `--fb-input-padding-y`.          |
| `.shadow-input`           | Input shadow                                                                          | Maps to `--fb-input-shadow`.             |
| `.rounded-option`         | Select/multi-select/ranking/picture-select option containers                          | Controls option border radius token.     |
| `.bg-option-bg`           | Unselected option backgrounds                                                         | Maps to `--fb-option-bg-color`.          |
| `.bg-option-selected-bg`  | Selected option backgrounds                                                           | Used for selected states.                |
| `.bg-option-hover-bg`     | Option hover background                                                               | Used for hover states.                   |
| `.border-option-border`   | Option borders and dropdown search divider                                            | Maps to option border token.             |
| `.text-option`            | Option label font size                                                                | Maps to `--fb-option-font-size`.         |
| `.text-option-label`      | Option label text color                                                               | Maps to `--fb-option-label-color`.       |
| `.font-option`            | Option label font family                                                              | Maps to `--fb-option-font-family`.       |
| `.font-option-weight`     | Option label font weight                                                              | Maps to `--fb-option-font-weight`.       |
| `.px-option-x`            | Option horizontal padding                                                             | Maps to `--fb-option-padding-x`.         |
| `.py-option-y`            | Option vertical padding                                                               | Maps to `--fb-option-padding-y`.         |
| `.rounded-button`         | Button radius (base button component)                                                 | Maps to `--fb-button-border-radius`.     |
| `.text-button`            | Button text size                                                                      | Maps to `--fb-button-font-size`.         |
| `.font-button-weight`     | Button font weight                                                                    | Maps to `--fb-button-font-weight`.       |
| `.border-brand`           | Selected/active option borders                                                        | Uses survey brand color token.           |

# Framework Guides
Source: https://formbricks.com/docs/surveys/website-app-surveys/framework-guides

Easily add the Formbricks App Survey SDK to your app with guides for different frameworks.

Integrate the **Formbricks App Survey SDK** into your app using multiple options. Explore the available choices below. If you need something else, open a [**GitHub Discussion**](https://github.com/formbricks/formbricks/discussions), and we’ll be happy to help!

<Info>
  **Important for Self-Hosted Setups:**

**Multi-Domain Setup:** If you are using the multi-domain setup, the `appUrl` parameter in all SDK configurations should point to your **public domain** (PUBLIC\_URL environment variable). This is the domain where surveys and public-facing content are served, which may be different from your admin interface domain (WEBAPP\_URL).

**Single Domain Setup:** If you are using the single domain setup, the `appUrl` parameter in all SDK configurations should point to your **admin domain** (WEBAPP\_URL environment variable).
</Info>

<CardGroup>
  <Card title="HTML" icon="html5" href="#html">
    All you need to do is add three lines of code to your HTML script, and that's it!
  </Card>

<Card title="React.js" icon="react" href="#react-js">
    Load our JavaScript library with your Workspace ID, and you're ready to
    go!
  </Card>

<Card title="Next.js" icon="react" href="#next-js">
    Natively add us to your Next.js app, with support for both App Router and Pages Router setups.
  </Card>

<Card title="Vue.js" icon="vuejs" href="#vue-js">
    Learn how to use Formbricks' Vue.js SDK to integrate your surveys into Vue.js applications.
  </Card>

<Card title="React Native" icon="react" href="#react-native">
    Easily integrate our SDK with your React Native app for seamless survey
    support.
  </Card>

<Card title="Swift" icon="swift" href="#swift">
    Use our iOS SDK to quickly integrate surveys into your iOS
    applications.
  </Card>

<Card title="Android" icon="android" href="#android">
    Integrate surveys into your Android applications using our native Kotlin
    SDK.
  </Card>

<Card title="Flutter" icon="flutter" href="#flutter">
    Add surveys to your Flutter app on iOS and Android with our Dart SDK.
  </Card>
</CardGroup>

## Prerequisites

Before getting started, make sure you have:

* A running web application with user authentication in your chosen framework.

* A Formbricks account with your **Workspace ID** and **API host**, available on the **Connect Your App** page under **Settings → Workspace**.

## HTML

All you need to do is copy a `<script>` tag to your HTML head:

```javascript theme={null}

<script type="text/javascript">
!function(){
    var appUrl = "https://app.formbricks.com"; // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
    var workspaceId = "<your-workspace-id>";
var t=document.createElement("script");t.type="text/javascript",t.async=!0,t.src=appUrl+"/js/formbricks.umd.cjs";t.onload=function(){window.formbricks.setup({workspaceId: workspaceId, appUrl: appUrl})};var e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(t,e)}();
</script>

```

### Required Customizations

| Name        | Type   | Description                            |
| ----------- | ------ | -------------------------------------- |
| workspaceId | string | Formbricks Workspace ID.               |
| appUrl      | string | URL of the hosted Formbricks instance. |

Now, visit the [Validate Your Setup](#validate-your-setup) section to verify your setup!

## React.js

Install the Formbricks SDK using one of the following package managers: `npm`, `pnpm`, or `yarn`.  
Note that **`zod`** is required as a peer dependency and must also be installed in your app.

```javascript npm theme={null}
npm install @formbricks/js zod
```

```bash pnpm theme={null}
pnpm add @formbricks/js zod
```

```bash yarn theme={null}
yarn add @formbricks/js zod
```

Update your `App.js/ts` file to initialize Formbricks.

```javascript src/App.js theme={null}
// other imports
import formbricks from "@formbricks/js";

if (typeof window !== "undefined") {
  formbricks.setup({
    workspaceId: "<workspace-id>",
    appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
  });
}

function App() {
  // your own app
}

export default App;
```

### Required Customizations

Now, visit the [Validate Your Setup](#validate-your-setup) section to verify your setup!

## Next.js

Next.js apps use either the **App Directory** or the **Pages Directory**. Since the Formbricks SDK runs on the client side, follow these steps based on your setup:

* **App Directory**: Create a new component in `app/formbricks.tsx` and call it in `app/layout.tsx`.

* **Pages Directory**: Initialize Formbricks directly in `_app.tsx`.

Code snippets for the integration for both conventions are provided to further assist you.

```bash npm theme={null}
npm install @formbricks/js zod
```

```bash pnpm theme={null}
pnpm add @formbricks/js zod
```

```bash yarn theme={null}
yarn add @formbricks/js zod
```

### App directory

```typescript app/formbricks.tsx theme={null}
"use client";

import { usePathname, useSearchParams } from "next/navigation";
import { useEffect } from "react";
import formbricks from "@formbricks/js";

export default function FormbricksProvider() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

useEffect(() => {
    formbricks.setup({
      workspaceId: "<workspace-id>",
      appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
    });
  }, []);

useEffect(() => {
    formbricks?.registerRouteChange();
  }, [pathname, searchParams]);

return null;
}
```

```typescript app/layout.tsx theme={null}
// other imports
import FormbricksProvider from "./formbricks";
import { Suspense } from "react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <Suspense>
        <FormbricksProvider />
      </Suspense>
      <body>{children}</body>
    </html>
  );
}
```

### Pages directory

```javascript src/pages/_app.tsx theme={null}
// other import
import { useRouter } from "next/router";
import { useEffect } from "react";
import formbricks from "@formbricks/js";

export default function App({ Component, pageProps }: AppProps) {
  const router = useRouter();

useEffect(() => {
    // Connect next.js router to Formbricks
    const handleRouteChange = formbricks?.registerRouteChange;
    router.events.on("routeChangeComplete", handleRouteChange);

return () => {
      router.events.off("routeChangeComplete", handleRouteChange);
    };
  }, []);
  return <Component {...pageProps} />;
}
```

### Required Customizations

First, initialize the Formbricks SDK to run only on the client side. To track page changes, register the route change event with the Next.js router.

Next, go to the [**Validate Your Setup**](#validate-your-setup) section to verify your setup!

## Vue.js

Integrating the Formbricks SDK with Vue.js is easy. We'll ensure the SDK is only loaded and used on the client side, as it's not meant for server-side use.

```bash npm theme={null}
npm install @formbricks/js
```

```bash pnpm theme={null}
pnpm add @formbricks/js
```

```bash yarn theme={null}
yarn add @formbricks/js
```

```javascript src/formbricks.js theme={null}
import formbricks from "@formbricks/js";

export default formbricks;
```

```javascript src/main.js theme={null}
// other imports
import formbricks from "@/formbricks";

const app = createApp(App);

app.use(router);

app.mount("#app");

router.afterEach((to, from) => {
  if (typeof formbricks !== "undefined") {
    formbricks.registerRouteChange();
  }
});
```

### Required Customizations

Now, visit the [Validate Your Setup](#validate-your-setup) section to verify your setup!

## React Native

<Info>
  **Interaction-based Segments:** targeting users by whether they have seen, started or completed a survey requires **@formbricks/react-native 3.1.0** or higher. See [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments).
</Info>

Install the Formbricks React Native SDK using one of the package managers, i.e., npm, pnpm, or yarn.

```bash npm theme={null}
npm install @formbricks/react-native
```

```bash pnpm theme={null}
pnpm add @formbricks/react-native
```

```bash yarn theme={null}
yarn add @formbricks/react-native
```

Now, update your `App.js/App.tsx` file to initialize Formbricks:

```javascript src/App.js theme={null}
// other imports
import Formbricks from "@formbricks/react-native";

const config = {
  workspaceId: "<workspace-id>",
  appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
};

export default function App() {
  return (
    <>
      {/* Your app content */}
      <Formbricks initConfig={config} />
    </>
  );
}
```

### Required Customizations

Now, visit the [Validate Your Setup](#validate-your-setup) section to verify your setup!

## Swift

<Info>**Minimum iOS Version:** The Formbricks iOS SDK requires **iOS 16.4** or higher.</Info>

<Info>
  **Interaction-based Segments:** targeting users by whether they have seen, started or completed a survey requires **FormbricksSDK 2.1.0** or higher. See [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments).
</Info>

Install the Formbricks iOS SDK using the following steps:

**Swift Package Manager**

1. In Xcode choose **File → Add Packages…**
2. Enter your repo URL (e.g. `https://github.com/formbricks/ios.git`)
3. Choose version rule (e.g. "Up to Next Major" starting at `2.1.0`).
4. Import in your code:

```swift theme={null}
   import FormbricksSDK
   ```

**CocoaPods**

1. Add the following to your `Podfile`:

```ruby theme={null}
   platform :ios, '16.4'
   use_frameworks! :linkage => :static

target 'YourTargetName' do
     pod 'FormbricksSDK', '~> 2.1'
   end
   ```

2. Run `pod install` in your app directory

3. Import in your code:
   ```swift theme={null}
   import FormbricksSDK
   ```

Now start using FormbricksSDK

```swift theme={null}
import FormbricksSDK

// 1. Build your config (you can also inject userId + attributes here)
let config = FormbricksConfig.Builder(
        appUrl: "https://your‑app.bricks.com", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
        workspaceId: "YOUR_WORKSPACE_ID"
    )
    .setLogLevel(.debug)
    .build()

// 2. Initialize the SDK (once per launch)
Formbricks.setup(with: config)

// 3. Identify the user
Formbricks.setUserId("user‑123")

// 4. Track events
Formbricks.track("button_pressed")

// 5. Set or add user attributes
Formbricks.setAttribute("blue", forKey: "favoriteColor")
Formbricks.setAttributes([
    "plan": "pro",
    "tier": "gold"
])

// 6. Change language (no userId required):
Formbricks.setLanguage("de")

// 7. Log out (no userId required):
Formbricks.logout()

// 8. Clean up SDK state (optional):
Formbricks.cleanup(waitForOperations: true) {
    print("SDK torn down")
}
```

### Required Customizations

Now, visit the [Validate Your Setup](#validate-your-setup) section to verify your setup!

## Android

<Info>
  **Minimum Android Version:** The Formbricks Android SDK requires **Android 10 (API level 29)** or higher.
</Info>

<Info>
  **Interaction-based Segments:** targeting users by whether they have seen, started or completed a survey requires **com.formbricks:android 2.1.0** or higher. See [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments).
</Info>

Install the Formbricks Android SDK using the following steps:

### Installation

Add the Maven Central repository and the Formbricks SDK dependency to your application's `build.gradle.kts`:

```kotlin theme={null}
repositories {
    google()
    mavenCentral()
}

dependencies {
    implementation("com.formbricks:android:2.1.0") // or a later version
}
```

Enable DataBinding in your app's module build.gradle.kts:

```kotlin theme={null}
android {
  buildFeatures {
    dataBinding = true
  }
}
```

### Usage

```kotlin theme={null}
// 1. Initialize the SDK
val config = FormbricksConfig.Builder(
    "https://your-formbricks-server.com",
    "YOUR_WORKSPACE_ID"
)
  .setLoggingEnabled(true)
  .setFragmentManager(supportFragmentManager)
  .build()

// 2. Setup Formbricks
Formbricks.setup(this, config)

// 3. Identify the user
Formbricks.setUserId("user‑123")

// 4. Track events
Formbricks.track("button_pressed")

// 5. Set or add user attributes
Formbricks.setAttribute("test@web.com", "email")
Formbricks.setAttributes(mapOf(Pair("attr1", "val1"), Pair("attr2", "val2")))

// 6. Change language (no userId required):
Formbricks.setLanguage("de")

// 7. Log out:
Formbricks.logout()
```

### Required Customizations

## Flutter

<Info>
  **Platform Support:** The Formbricks Flutter SDK targets **iOS and Android only**. Flutter Web and desktop are not supported.
</Info>

<Info>
  **Interaction-based Segments:** targeting users by whether they have seen, started or completed a survey requires **formbricks 1.1.0** or higher. See [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic#level-4-interaction-based-segments).
</Info>

Install the Formbricks Flutter SDK from [pub.dev](https://pub.dev/packages/formbricks):

```bash theme={null}
flutter pub add formbricks
```

### Usage

Mount the `Formbricks` widget once, high in your widget tree (e.g. alongside your app's home). It initializes the SDK on mount and renders any triggered survey in a modal overlay:

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:formbricks/formbricks.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

@override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Stack(
        children: [
          const HomePage(),
          // Initializes the SDK and hosts the survey overlay.
          Formbricks(
            appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
            workspaceId: "<workspace-id>",
          ),
        ],
      ),
    );
  }
}
```

Then drive the SDK through its static API from anywhere:

```dart theme={null}
// 1. Trigger a code action — shows a matching, eligible survey.
await Formbricks.track("button_clicked");

// 2. Identify the current user.
await Formbricks.setUserId("user_123");

// 3. Set or add user attributes.
await Formbricks.setAttribute("plan", "pro");
await Formbricks.setAttributes({"plan": "pro", "mrr": 99, "signup_date": DateTime.now()});

// 4. Set the survey language.
await Formbricks.setLanguage("de");

// 5. Reset to an anonymous session on sign-out.
await Formbricks.logout();
```

<Note>
  Prefer to initialize before any UI mounts? Call `Formbricks.setup(appUrl: ..., workspaceId: ...)` directly — the widget still needs to be in the tree to render surveys, but it won't re-run setup (setup is idempotent). All static methods are sequenced through an internal command queue, so calls run in submission order and return a `Future<Result<void, FormbricksError>>`.
</Note>

### Public API

| Method                                              | Description                                                              |
| --------------------------------------------------- | ------------------------------------------------------------------------ |
| `Formbricks(appUrl:, workspaceId:, logLevel:)`      | Host widget — initializes the SDK and renders triggered surveys.         |
| `Formbricks.setup({appUrl, workspaceId, logLevel})` | Imperative initialization. Idempotent.                                   |
| `Formbricks.track(String name)`                     | Fire a code action; shows a matching eligible survey.                    |
| `Formbricks.setUserId(String userId)`               | Identify the contact. Switching ids resets the prior user's state first. |
| `Formbricks.setAttribute(String key, Object value)` | Set one attribute (`String` / `num` / `DateTime`).                       |
| `Formbricks.setAttributes(Map<String, Object>)`     | Set several attributes at once.                                          |
| `Formbricks.setLanguage(String language)`           | Set the survey language.                                                 |
| `Formbricks.logout()`                               | Reset to an anonymous session.                                           |

Attribute keys must be lowercase letters, numbers, and underscores, and start with a letter. `DateTime` values are sent as UTC ISO-8601 strings; numbers stay numbers. Identity and attribute changes are debounced (\~500 ms) and coalesced into a single backend request.

### Required Customizations

<Note>
  Surveys render by loading `{appUrl}/js/surveys.umd.cjs` in a WebView, so that URL must be reachable from the device. Formbricks Cloud and standard self-hosted instances serve this script automatically. Config is persisted with `shared_preferences` and is **not encrypted at rest** — avoid putting sensitive PII in attribute values.
</Note>

Now, visit the [Validate Your Setup](#validate-your-setup) section to verify your setup!

## Validate your setup

Once you've completed the steps above, validate your setup by checking the Setup Checklist on the **Connect Your App** page under **Settings → Workspace**. The widget status indicator should change from this:

![first validate](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738122589/image_ecaovs.jpg)
To this:

![second validate](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738122750/image_ymaenn.jpg)

## Debugging Formbricks Integration

<Note>
  The debug mode is only available in the JavaScript SDK and works exclusively in the browser. It is not
  supported in mobile SDKs such as React Native, iOS, Android, or Flutter.
</Note>

Enabling debug mode in your browser can help troubleshoot issues with Formbricks. Here's how to activate it and what to look for in the logs.

### Activate Debug Mode

To enable debug mode, add `?formbricksDebug=true` to your app's URL (e.g., [`https://example.com?formbricksDebug=true)`](https://example.com?formbricksDebug=true\)).

#### View Debug Logs

1. Open your browser's developer tools:

* **Google Chrome/Edge**: Press `F12` or right-click and select "**Inspect" > "Console**".

* **Firefox**: Press `F12` or right-click and select "**Inspect Element" > "Console**".

* **Safari**: Press `Option + Command + C` to open developer tools and go to the "**Console**" tab.

#### Common Use Cases

Debug mode is helpful for:

* Verifying Formbricks initialization.

* Identifying issues with survey triggers.

* Troubleshooting unexpected behavior.

#### Debug Log Messages

Logs provide insights into:

* API calls and responses.

* Survey triggers and form interactions.

* Initialization errors.

If you're stuck, visit [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions) for assistance.

```
```

# Google Tag Manager
Source: https://formbricks.com/docs/surveys/website-app-surveys/google-tag-manager

Deploy Formbricks surveys through GTM without modifying your website code.

## Prerequisites

* [Google Tag Manager](https://tagmanager.google.com/) installed on your website
* Your Formbricks **Workspace ID** (Settings → Workspace → Connect Your App)
* Your **App URL**: `https://app.formbricks.com` (or your self-hosted URL)

<Note>
  Use PUBLIC\_URL for multi-domain setups, WEBAPP\_URL for single-domain setups.
</Note>

## Basic Setup

<Steps>
  <Step title="Create a Custom HTML tag in GTM">
    1. Create a new tag with preferred name e.g. "Formbricks Intercept Surveys"
    2. Tag Type: Custom HTML
    3. Paste the code from Step 2. Make sure to replace `<your-workspace-id>` and if you self-host, replace `<your-app-url>`
  </Step>

<Step title="Add initialization script">
    ```html theme={null}
    <script type="text/javascript">
    !function(){
        var appUrl = "https://app.formbricks.com"; // REPLACE ONLY IF YOUR SELF-HOST
        var workspaceId = "<your-workspace-id>"; // REPLACE
        var t=document.createElement("script");
        t.type="text/javascript";
        t.async=!0;
        t.src=appUrl+"/js/formbricks.umd.cjs";
        t.onload=function(){
            window.formbricks && window.formbricks.setup({
                workspaceId: workspaceId,
                appUrl: appUrl
            });
        };
        var e=document.getElementsByTagName("script")[0];
        e.parentNode.insertBefore(t,e);
    }();
    </script>
    ```

<Step title="Set trigger">
    1. Trigger: **All Pages** - Page View (default) or use case specific event
    2. Save and publish
       <img alt="Add a trigger" />
  </Step>

<Step title="Test">
    1. Use GTM Preview mode
    2. Verify the tag fires
    3. Add `?formbricksDebug=true` to the URL to see test logs in browser console (see [Debugging Mode](/docs/surveys/website-app-surveys/framework-guides#debugging-formbricks-integration) for more details)
  </Step>
</Steps>

## User Identification

Identify users to enable targeting and attributes. Learn more about [user identification](/docs/surveys/website-app-surveys/user-identification).

<Note>
  User identification is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

<Steps>
  <Step title="Create GTM variables">
    1. Go to Variables on GTM dashboard
    2. Create new User-defined variable
    3. Name it (e.g., "User ID")
    4. Variable Type: Data Layer Variable
    5. Data Layer Variable: "userId"
    6. Save and publish
    7. Repeat for attributes you want to track e.g. "userEmail" and "userPlan" (optional)

<Step title="Create identification tag">
    New Custom HTML tag named "Formbricks - User":

```html theme={null}
    <script>
    (function() {
        var check = setInterval(function() {
            if (window.formbricks && window.formbricks.setUserId) {
                clearInterval(check);
                var userId = {{User ID}};
                if (userId) {
                    window.formbricks.setUserId(userId);
                    var attrs = {};
                    if ({{User Email}}) attrs.email = {{User Email}};
                    if ({{User Plan}}) attrs.plan = {{User Plan}};
                    if (Object.keys(attrs).length) {
                        window.formbricks.setAttributes(attrs);
                    }
                }
            }
        }, 100);
        setTimeout(function() { clearInterval(check); }, 10000);
    })();
    </script>
    ```
  </Step>

<Step title="Set trigger and push data">
    1. Create a custom event trigger in GTM

2. Trigger Type: Custom Event

3. Event name: `user-login` (or your preferred event name)

4. Attach this trigger to your "Formbricks - User" tag

5. Save and publish

6. In your code, push data with the same event name:

```javascript theme={null}
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
        'event': 'user-login',
        'userId': 'user-123',
        'userEmail': 'user@example.com',
        'userPlan': 'premium'
    });
    ```
  </Step>
</Steps>

## Track Custom Events

<Steps>
  <Step title="Create code action in Formbricks">
    Add code action via Formbricks UI

<Step title="Create GTM variable for Event Name">
    1. Go to Variables on GTM dashboard
    2. Create new User-defined variable
    3. Name it "Event Name"
    4. Variable Type: Data Layer Variable
    5. Data Layer Variable: "eventName"
    6. Save and publish

<Step title="Create event tracking tag">
    New Custom HTML tag:

```html theme={null}
    <script>
    if (window.formbricks && window.formbricks.track) {
        window.formbricks.track({{Event Name}});
    }
    </script>
    ```
  </Step>

<Step title="Create custom trigger">
    1. Create a custom event trigger in GTM
    2. Trigger Type: Custom Event
    3. Event name: `eventName` or name that matches with your event in code.
    4. Attach this trigger to your event tracking tag
    5. Save and publish

<Step title="Fire events from your site">
    ```javascript theme={null}
    // Track button click
    window.dataLayer.push({
        'event': 'eventName',
        'eventName': 'code-action'
    });
    ```
  </Step>
</Steps>

## Troubleshooting

**Surveys not showing?**

* Use GTM Preview mode to check tag firing
* Add `?formbricksDebug=true` to your URL
* Check browser console for errors
* Wait 1 minute for the Server Cache to refresh

**User ID not working?**

* Verify Data Layer push syntax
* Check GTM variables are reading correct values
* Ensure user tag fires after initialization

**Events not tracking?**

* Confirm `window.formbricks` exists before calling track
* Match event names exactly with Formbricks action names
* Check timing - Formbricks must be initialized first

## Need Help?

* [GitHub Discussions](https://github.com/formbricks/formbricks/discussions)
* [Framework Guides](/docs/surveys/website-app-surveys/framework-guides)
* [Actions](/docs/surveys/website-app-surveys/actions)
* [User Identification](/docs/surveys/website-app-surveys/user-identification)

# Quickstart - Web & App Surveys
Source: https://formbricks.com/docs/surveys/website-app-surveys/quickstart

App surveys deliver 6–10x higher conversion rates compared to email surveys. If you are new to Formbricks, follow the steps in this guide to launch a survey in your web or mobile app (React Native) within 10–15 minutes.

<Steps>
  <Step title="Create a Formbricks cloud account">
    While you can [self-host](/docs/self-hosting) Formbricks, the fastest and easiest way to get started is with the free Cloud plan. Simply [sign up](https://app.formbricks.com/auth/signup) here, follow the onboarding steps, and choose the "Formbricks Surveys" option.

![what are you here for](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738113228/image_d11uiy.png)
  </Step>

<Step title="Choose 'In-product surveys'">
    You can create In-product and Link Surveys with both options, but the onboarding will prompt you to connect your app/website to Formbricks.

<Step title="Connect your App/Website">
    Follow the instructions to connect your app or website: ![connect product to
    formbricks](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738114328/image_tv0jmj.png)
  </Step>

<Step title="Confirm setup">
    As soon as Formbricks receives the first data point, you will see a message in the onboarding:

![congrats](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738114793/image_lij7kw.png)

Onboarding is complete! Now let's create our first survey as you should see templates to choose from after clicking on **Next**:

![first survey](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738115025/image_yyuuzn.jpg)
  </Step>

<Step title="Create your first survey">
    To be able to see a survey in your app, you need to create one. We'll choose one of the templates and head over to the survey settings:

Pick the Survey Type as **Website & App Survey**.
  </Step>

<Step title="Create trigger to show survey">
    Scroll to **Survey Trigger**, click **+ Add Action**, and select **Page View**. This ensures the survey appears when the Formbricks Widget detects any page load.

<Step title="Set Recontact Options right">
    A common hiccup is users seeing one survey but it doesn't appear again. This is due to the default settings we chose to avoid survey fatigue. While setting up, we recommend the following Recontact Options:

<Note>
      Please change this setting after testing your survey to avoid user fatigue.
    </Note>
  </Step>

<Step title="Publish the survey">
    Publish the survey to make it available for the SDK to pull into the website or app where you want to show
    it.
  </Step>

<Step title="Understand caching behavior">
    For better scalability, we cache the request the SDK makes to the server. This allows you to use Formbricks
    on websites with millions of visitors without high hosting cost.

<Note>
      **Important**: Any changes to surveys, action classes, or Workspace settings will
      take **up to 1 minute** to reflect in your app/website due to server-side caching. This includes survey
      modifications, new triggers, styling changes, and other updates.
    </Note>

For troubleshooting, you can enable [Debug
    Mode](/docs/surveys/website-app-surveys/framework-guides#activate-debug-mode) to see detailed logs
    in your browser console.
  </Step>

<Step title="Check browser compatibility">
    Formbricks is designed to work with all modern browsers. Please ensure your users are using a supported version:

*Internet Explorer is not supported.*
  </Step>
</Steps>

Need help? Join us in [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions), and we'll be happy to assist!

# Recontact Options
Source: https://formbricks.com/docs/surveys/website-app-surveys/recontact

Recontact Options control how often a single survey is shown to the same user, helping you balance effective feedback collection with a positive user experience by preventing survey fatigue.

Recontact Options are the **per-survey** control for how often *this* survey may reappear to the same person. They are one layer of the full display logic — see [Survey Display Logic](/docs/surveys/website-app-surveys/survey-display-logic) for how they combine with targeting, the Cooldown Period, and triggers.

<Note>By default, a survey is shown to each user only once.</Note>

## Configuring Recontact Options

1. Open the Survey Editor and select the **Settings** tab.
2. Ensure the survey type is set to **App Survey**.
3. Open the **Visibility & Recontact** section and choose an option under **Recontact options**.

Available options:

* **Show only once** *(default)* — show a single time, even if the user does not respond.
* **Show a limited number of times** — show at most the specified number of times, or until the user responds (whichever comes first).
* **Ask until they submit a response** — keep showing whenever triggered until a response or partial response is submitted.
* **Keep showing while conditions match** — allow multiple responses and keep showing even after a response. Useful for continuous feedback collection, such as the [Docs Feedback Survey](/docs/surveys/best-practices/docs-feedback) or the [Feedback Box](/docs/surveys/best-practices/feedback-box).

Each option counts *this* survey's own displays and responses only.

## Relationship to the Cooldown Period

Recontact Options decide how often a survey may repeat; the [Cooldown Period](/docs/surveys/website-app-surveys/cooldown-period) is a separate, workspace-wide gate that limits how often a user sees *any* survey. Both must pass before a survey is shown — Recontact Options are evaluated first, then the Cooldown Period.

***

Still struggling or is something not working as expected? [Join us in GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you!

# Survey % of Users
Source: https://formbricks.com/docs/surveys/website-app-surveys/show-survey-to-percent-of-users

Formbricks allows you to display surveys to only a percentage of your targeted users. This is helpful for surveying on public facing website.

To target specific segments of your audience or manage survey exposure, Formbricks allows you to display surveys to only a random selection of your targeted users.

## How to set up percentage-based visibility

<Steps>
  <Step title="Open settings in survey editor">
    In the Survey Editor, click on the **`Settings`** tab
  </Step>

<Step title="Find 'Survey Trigger' card">
    Locate the 'Survey Trigger' card in the settings panel
  </Step>

<Step title="Enable percentage toggle">
    Find and enable the **`Show Survey to % of Users`** toggle
  </Step>

<Step title="Set percentage">
    Enter the desired percentage (from 0.01% to 100%) of users to whom the survey will be shown

<Note>
  Please note that this feature operates based on mathematical probabilistic
  functions, which may result in slight variations in the exact percentage of
  users who see the survey.
</Note>

### **Example Usage**

For instance, if you want to expose your survey to only half of your targeted user base, simply adjust the slider to show the survey to 50% of your users. This functionality allows you to conduct A/B testing or control the rollout of new surveys to gauge initial reactions before a wider release.

### **Application**

It's effective for:

* **A/B Testing**: Compare different user experiences by showing different surveys or survey variations to different segments of your audience.

* **Gradual Rollouts**: Gradually introduce a new survey to a portion of your users to monitor initial responses and adjust based on feedback before full deployment.

* **Load Management**: Manage server load and response processing by limiting the number of responses collected at any given time.

## **Conclusion**

Using the **Show Survey to % of Users** feature allows for precise control over who sees your Formbricks surveys, making it an invaluable feature for targeted data collection and user experience management. By adjusting survey visibility settings, you can strategically engage segments of your audience, enhance survey testing phases, and optimize overall survey effectiveness.

# Survey Display Logic
Source: https://formbricks.com/docs/surveys/website-app-surveys/survey-display-logic

How Formbricks decides whether to show an app survey to a user — from the simplest always-on setup to Recontact Options, the workspace Cooldown Period, segment targeting, and interaction-based segments.

Whether an app survey is shown to a given user comes down to a matching **trigger** plus a few independent **eligibility gates**. When a trigger fires, the survey appears only if it passes **all** of the gates. This page builds that model up one layer at a time, from the simplest case to the most advanced.

Formbricks decides a survey's eligibility from three gates, evaluated in this order:

1. **Recontact Options** — how often may *this* survey be shown to the same user?
2. **Cooldown Period** — has enough time passed since the user last saw *any* survey?
3. **Targeting** — is the user in the survey's audience?

A **Trigger** (a matching action) is the event that then shows an already-eligible survey — it is not a fourth gate, it is what starts a display attempt. The gates are computed up front (on load and whenever the user's data syncs); the trigger is checked against that result.

## Level 0 — Always show

Take a survey with **no targeting**, **no Cooldown Period**, and Recontact set to **"Keep showing while conditions match"**. Nothing gates it, so it shows **every time its trigger fires**. Simple, but usually too aggressive for anything but a persistent feedback button.

```mermaid theme={null}
flowchart LR
    T["Trigger fires"] --> S["Show survey"]
```

## Level 1 — Recontact Options (per survey)

Recontact Options control how often a single survey may reappear. They count *this* survey's own displays and responses, so they are genuinely **per survey**:

| Option                                  | Shows the survey…                            |
| --------------------------------------- | -------------------------------------------- |
| **Show only once** (default)            | once, ever                                   |
| **Show a limited number of times**      | up to N displays, or until the user responds |
| **Ask until they submit a response**    | on each trigger until the user responds      |
| **Keep showing while conditions match** | on every trigger (Level 0)                   |

**Example:** an onboarding survey set to *Ask until they submit a response* keeps appearing on each trigger until the user answers, then stops.

```mermaid theme={null}
flowchart LR
    T["Trigger fires"] --> R{"Already shown<br/>enough times?"}
    R -->|"no"| S["Show survey"]
    R -->|"yes"| X["Skip"]
```

See [Recontact Options](/docs/surveys/website-app-surveys/recontact) for setup.

## Level 2 — Cooldown Period between surveys

On top of per-survey recontact, a **Cooldown Period** enforces a minimum gap between surveys. Two settings feed it, but they share **one clock**:

* **Workspace Cooldown Period** (default **7 days**): after a user sees *any* survey, no survey shows again for the Cooldown Period.
* **Per-survey override** (*Ignore Cooldown Period* / *Set custom Cooldown Period*): replaces the workspace number **for that survey only**.

<Warning>
  The Cooldown Period is measured from the last time the user saw **any** survey — not from the last time they saw *this* one. So a per-survey "wait 90 days" really means "90 days since the user saw *any* survey," which frequently-shown surveys keep resetting. The per-survey number changes the *value*, not the *clock*. To gate one survey on its **own** schedule, use interaction-based segments (Level 4).
</Warning>

**Example:** with the default 7-day Cooldown Period, showing any short survey today blocks *every* survey — including a quarterly NPS — for the next 7 days.

```mermaid theme={null}
flowchart LR
    T["Trigger fires"] --> R{"Recontact:<br/>shown enough?"}
    R -->|"yes"| X["Skip"]
    R -->|"no"| W{"Enough days since<br/>ANY survey shown?"}
    W -->|"no"| X
    W -->|"yes"| S["Show survey"]
```

See [Cooldown Period](/docs/surveys/website-app-surveys/cooldown-period) for setup.

## Level 3 — Targeting with Segments

<Note>
  Targeting is part of [Attribute-based Targeting](/docs/surveys/website-app-surveys/attribute-based-targeting), included in the [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

Targeting restricts **who** is eligible. A survey can be assigned a Segment built from **Attributes**, other **Segments**, and **Devices**. Only users who match the Segment pass this layer; everyone else never sees the survey, regardless of triggers or the Cooldown Period.

**Example:** a Segment `plan = "pro"` means only Pro users are eligible for the survey.

```mermaid theme={null}
flowchart LR
    T["Trigger fires"] --> P{"Recontact &<br/>Cooldown Period OK?"}
    P -->|"no"| X["Skip"]
    P -->|"yes"| S{"User in the<br/>survey's Segment?"}
    S -->|"no"| X
    S -->|"yes"| Show["Show survey"]
```

See [Attribute-based Targeting](/docs/surveys/website-app-surveys/attribute-based-targeting) for setup.

## Level 4 — Interaction-based Segments

Interaction-based segments add a fourth Segment filter type: target users by **how they interacted with your surveys** — seen, started, or completed within a recent window. Because these look at a *specific* survey's own displays and responses, they do what the shared Cooldown Period clock cannot.

<Info>
  **Mobile apps need a recent Formbricks SDK** — `FormbricksSDK` 2.1.0 on iOS, `com.formbricks:android` 2.1.0, `@formbricks/react-native` 3.1.0, or `formbricks` 1.1.0 on Flutter. Older SDKs target the wrong people here, silently — see the warning at the end of this section. Web has no minimum.
</Info>

A filter reads as one sentence:

> `<operator>` `<any survey | specific surveys>` **within** `<number>` `<days | weeks | months>`

### Interaction operators

| Operator                       | Matches users who…                                          |
| ------------------------------ | ----------------------------------------------------------- |
| **have seen**                  | were shown the survey within the window                     |
| **have not seen**              | were **not** shown the survey within the window             |
| **have started responding to** | opened and answered at least one question (finished or not) |
| **have completed**             | submitted a completed response within the window            |
| **have not completed**         | have **no** completed response within the window            |

<Note>
  **"have started responding to" vs "have not completed" are not opposites.** *Have started* requires the user to have engaged at least once. *Have not completed* is the negation of *have completed*, so it also matches everyone who never saw or started the survey — use it as an **exclusion**, not stand-alone targeting. To target **drop-offs**, combine both with `AND`: *have started responding to A* **AND** *have not completed A*.
</Note>

### Primary use case: a true per-survey Cooldown Period

This is what interaction segments unlock over the built-in Cooldown Period. To show an **NPS survey on its own \~3-month cadence**, driven by that survey's own history rather than the shared cross-survey clock:

* **Recontact:** *Keep showing while conditions match*.
* **Cooldown Period:** set a **small** custom value (e.g. *1 day*) — a short guard so it can't repeat within a session (see the note below). Do **not** use *Ignore Cooldown Period*.
* **Targeting Segment:** `have not seen NPS within 3 months` (specific survey = NPS).

The Segment provides the real 3-month per-survey cadence; the small Cooldown Period is only a short-term guard.

```mermaid theme={null}
flowchart LR
    T["Trigger fires"] --> I{"Seen NPS in the<br/>last 3 months?"}
    I -->|"yes"| X["Skip"]
    I -->|"no"| S["Show NPS"]
```

### Other use cases

* **Follow-up funnel:** a detail survey targets `have completed NPS within 30 days`.
* **Re-engage drop-offs:** `have started responding to Onboarding AND have not completed Onboarding within 14 days`.

<Note>
  **Interaction membership refreshes on sync, not instantly.** Recontact and the Cooldown Period react the moment a survey is shown; interaction-segment membership is recalculated when the user's data syncs — on load, when you set a user ID or attributes, and after a survey is displayed, answered or completed. On a supported SDK version that lag is irrelevant for long windows like the 3-month cadence above, since the short Cooldown Period guard covers it — but don't rely on interaction filters for *instant* re-display suppression, and don't pair one with *Show only once*, which already blocks re-display permanently.
</Note>

<Warning>
  **On mobile, this needs a recent SDK.** The post-interaction refresh only exists from `FormbricksSDK` **2.1.0** (iOS), `com.formbricks:android` **2.1.0**, `@formbricks/react-native` **3.1.0** and `formbricks` **1.1.0** (Flutter). Older versions keep the segment list they received when the app started, so interaction filters go stale for the whole session: a survey can keep appearing after the user has already seen or completed it, and one that just became eligible won't appear until the app is relaunched. A short Cooldown Period does not compensate — it expires while the membership is still stale. Nothing errors, the targeting is simply wrong. See the [Framework Guides](/docs/surveys/website-app-surveys/framework-guides) for each SDK's install snippet.
</Warning>

## Putting it all together

```mermaid theme={null}
flowchart TD
    A["Visitor loads or identifies"] --> B["Formbricks syncs and calculates<br/>which Segments the visitor is in<br/>(including survey-interaction filters)"]
    B --> T{"Trigger:<br/>does a matching action fire?"}
    T -->|no| WAIT["Waits for a trigger"]
    T -->|yes| R{"Recontact Options:<br/>display count for THIS survey satisfied?"}
    R -->|no| X["Survey not shown"]
    R -->|yes| W{"Cooldown Period:<br/>enough days since the last survey shown?<br/>(per-survey value or workspace Cooldown Period)"}
    W -->|no| X
    W -->|yes| S{"Targeting:<br/>is the visitor in the survey's Segment?"}
    S -->|no| X
    S -->|yes| G["Survey shown, display recorded"]
    G -.->|"updates recontact & Cooldown Period state instantly"| R
    G -.->|"changes interaction-segment membership at next sync"| B
```

***

Still have questions or seeing unexpected behavior? [Join us in GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we'll be glad to help.

# User Identification
Source: https://formbricks.com/docs/surveys/website-app-surveys/user-identification

User Identification helps you to not only segment your users but also to see more information about the user who responded to a survey. This helps you to target surveys to specific user segments and see more information about the user who responded to a survey.

<Note>
  User identification is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license).
</Note>

### Understanding Identified vs Unidentified Users

In Formbricks, understanding the difference between identified and unidentified users is crucial for effective survey segmentation and targeted feedback collection.

| Feature                                                  | Unidentified Users | Identified Users |
| -------------------------------------------------------- | ------------------ | ---------------- |
| Show surveys based on **trigger** actions                | ✅                  | ✅                |
| Set **recontact details** to avoid survey fatique        | ✅                  | ✅                |
| Target a subset of users using **attributes & segments** | ❌                  | ✅                |
| Collect **user information** in Formbricks               | ❌                  | ✅                |
| Track **custom attributes**                              | ❌                  | ✅                |
| Counts towards your **monthly tacked user (MTU)** limit  | ❌                  | ✅                |
| Recommended for **public-facing websites**               | ✅                  | ❌                |
| Recommended for **web apps after login**                 | ❌                  | ✅                |

## Identified Users

Identified users are those for whom specific information has been set, notably the userId. This identification allows for more precise targeting of surveys and a deeper understanding of the feedback provided. When enabled, all information specified by you and all actions are sent to Formbricks.

This method is recommended for applications where users are required to log in and will often return.

### Setting User ID

To enable user identification, call the `setUserId` function of Formbricks and pass the user id. The user will show up in the Formbricks dashboard. Use a unique string, like a database ID or a unique email address. You can also anonymize the identifier, as long as it is unique for each user.

```javascript theme={null}
formbricks.setUserId("<user-id>");
```

## Setting Custom User Attributes

Use the `setAttribute` function to set custom attributes for the user (e.g., name, plan).

```javascript Setting Custom Attributes theme={null}
formbricks.setAttribute("Plan", "free");
```

The `setAttribute` function works like this:

```javascript Setting Custom Attributes theme={null}
formbricks.setAttribute("attribute_key", "attribute_value");
```

You can also set multiple attributes at once by passing an object to the `setAttributes` function:

```javascript Setting Multiple Custom Attributes theme={null}
formbricks.setAttributes({
  attribute_key_1: "attribute_value_1",
  attribute_key_2: "attribute_value_2",
});
```

<Note>
  **Note**: the number of different attribute classes (e.g., "Plan," "First Name," etc.) is currently limited
  to 150 attributes per environment.
</Note>

### Setting User Language

Use the `setLanguage` function to set the user's preferred language for surveys. This allows you to display surveys in the user's language when multi-language surveys are enabled. You can pass either the ISO language code (e.g., "de", "fr", "es") or the language alias you configured in **Settings → Workspace → Survey Languages**.

```javascript Setting User Language theme={null}
formbricks.setLanguage("de"); // ISO identifier or Alias set when creating language
```

### Logging Out Users

When a user logs out of your webpage, also log them out of Formbricks to prevent activity from being linked to the wrong user. Use the logout function:

```javascript Logging out User theme={null}
formbricks.logout();
```

# Migrate to Workspace ID
Source: https://formbricks.com/docs/surveys/website-app-surveys/workspace-id-migration

Learn why Environment IDs were deprecated, what still works today, and how to migrate your SDK setup to Workspace IDs.

Formbricks deprecated the legacy Environment ID for SDK setup and now uses **Workspace ID** as the primary identifier.

<Info>
  Existing SDK integrations that still use `environmentId` continue to work for now. New and updated integrations
  should use `workspaceId`.
</Info>

## Why This Changed

Formbricks moved from an environment-centric model to a workspace-centric model to simplify setup, reduce confusion,
and align product terminology across the app, SDKs, and API surfaces.

## Terms To Know

* **Workspace ID**: The canonical identifier for SDK setup and current product workflows.
* **Environment ID (legacy)**: A backward-compatible identifier that may still appear in older integrations.

## What Still Works

* SDK setups using `workspaceId` are the recommended and future-proof option.
* SDK setups using `environmentId` are still accepted during the migration period.
* If your app is already connected and sending data with a legacy Environment ID, no immediate outage is expected.

## Recommended Migration

<Steps>
  <Step title="Open Connect Your App">
    In Formbricks, go to **Settings → Workspace → Connect Your App**.
  </Step>

<Step title="Copy Your Workspace ID">
    Use the Workspace ID field as the canonical ID for all new SDK setup changes.
  </Step>

<Step title="Update SDK Initialization">
    Replace legacy `environmentId` config usage with `workspaceId` in your integration snippets.
  </Step>

<Step title="Keep appUrl Unchanged">
    Keep your existing `appUrl` value unless your hosting/domain setup changed.
  </Step>
</Steps>

## SDK Example

```javascript theme={null}
import formbricks from "@formbricks/js";

formbricks.setup({
  workspaceId: "<your-workspace-id>",
  appUrl: "<your-app-url>",
});
```

## FAQ

### Do I Need To Rotate IDs Immediately?

No. Legacy setups continue to work during the migration period. However, new implementations should always use
`workspaceId`.

### Do Test And Production Workflows Change?

No. Your development/testing and production workflows remain the same. This migration only changes the canonical
identifier you should use in SDK setup.

### Where Can I Find Detailed Setup Guides?

Use the [Framework Guides](https://formbricks.com/docs/surveys/website-app-surveys/framework-guides)
for framework-specific SDK instructions.

# Dashboards & Charts
Source: https://formbricks.com/docs/unify-feedback/dashboards-charts

Visualize Feedback Records and group charts onto shareable dashboards.

Dashboards & Charts let you turn Feedback Records into visual analytics. A **Chart** is a single visualization scoped to one Feedback Dataset. A **Dashboard** is a grid of charts you can share with your team.

## Charts

Charts live under **Workspace → Charts**. Each chart is a query plus a visualization config.

### Available chart types

| Type           | When to use                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------- |
| **Area Chart** | Trend over time with magnitude emphasis (cumulative volume, NPS trend with shaded area). Default. |
| **Bar Chart**  | Compare a measure across categories (responses per source, NPS by segment).                       |
| **Line Chart** | Trend over time without area fill (CSAT week-over-week, response rate).                           |
| **Pie Chart**  | Share-of-total across a small set of categories (channel mix, sentiment split).                   |
| **Big Number** | Headline KPI for a dashboard (total responses, avg NPS, % positive).                              |

You can build a chart in two ways:

### Manual builder

Pick a Feedback Dataset, choose dimensions and measures (count of records, average NPS, ...), apply filters, and select a chart type. Live preview updates as you tweak.

### AI builder

Describe what you want in natural language ("Average NPS by month over the last 90 days") and Formbricks generates the Cube query for you. You can edit the result in the manual builder afterwards.

The AI builder requires **Smart functionality (AI)** to be enabled at the organization level and a configured AI provider. See [AI Features](/docs/platform/features/ai-features).

## Dashboards

Dashboards live under **Workspace → Dashboards**. Each dashboard is a grid you can resize and arrange.

From a dashboard you can:

* **Create** a new chart inline and have it added automatically.
* **Add existing** charts.
* **Reorder and resize** widgets.
* **Duplicate** a chart for a quick variation.
* **Delete** a widget (the underlying chart stays in the workspace).

## Permissions

* Owners, Managers, and members with **Manage** or **Read & Write** access can create and edit dashboards and charts.
* Members with **Read** access can view dashboards and charts but cannot edit them.

## Requirements

* A Feedback Dataset with records.
* Workspace access to that dataset.

# Enrichment
Source: https://formbricks.com/docs/unify-feedback/enrichment

AI enrichment that adds sentiment, emotions, and a consolidated language to open-text Feedback Records.

Enrichment automatically adds AI-generated context to your open-text feedback. When a Feedback Record has a text answer (`value_text`), Formbricks analyzes it and attaches three kinds of enrichment:

* **Sentiment**: how positive or negative the feedback is.
* **Emotions**: which emotions the text expresses.
* **Language consolidation**: a translated copy of the text in one common language, so feedback written in different languages can be compared and analyzed together.

These fields turn free text, which is normally hard to count, into structured signals you can filter, chart, and trend over time.

## How enrichment works

Enrichment is **automatic and per-record**. Individual records are never triggered or configured by hand; the only setting is the translation target language, which is configured once at the service level (see [Language consolidation](#language-consolidation)):

1. A Feedback Record is ingested with a text answer in `value_text`.
2. Formbricks enriches the record **asynchronously**. The enrichment fields are absent until processing finishes, so a record may show as **Not enriched** for a short time after it arrives.
3. Once complete, the sentiment, emotion, and translation fields appear on the record and in charts.

Only records with open text receive AI enrichment. Records that only carry a rating, NPS score, or categorical choice have no text to analyze. Categorical answers are still consolidated across languages through their **Value ID**, which is not AI enrichment. See [Consolidating the same option across languages](#consolidating-the-same-option-across-languages).

<Note>
  Enrichment fields are read-only. Editing a record's `value_text` clears its
  enrichment and re-queues it for processing. Editing a record's `language`
  re-runs only the translation.
</Note>

## Sentiment enrichment

Sentiment classifies each text answer on a polarity scale and assigns a signed score.

**Sentiment label** is one of:

| Label             | Meaning                                     |
| ----------------- | ------------------------------------------- |
| **Very positive** | Strongly positive feedback                  |
| **Positive**      | Positive feedback                           |
| **Neutral**       | Neither positive nor negative               |
| **Negative**      | Negative feedback                           |
| **Very negative** | Strongly negative feedback                  |
| **Mixed**         | Contains both positive and negative signals |

**Sentiment score** is a number from **-1.0** (very negative) to **1.0** (very positive). `Mixed` records score near 0.

Where you see it:

* **Record detail drawer**, under the **AI enrichment** section, e.g. `Positive (0.82)`.
* **Topics & Subtopics**, as a colored sentiment badge on each record card.
* **Charts**, where you can group by **Sentiment** or chart the average **Sentiment Score**. Records that haven't been enriched yet fall into a **Not enriched** bucket.

## Emotion enrichment

Emotion enrichment detects which emotions a text answer expresses. It is **multi-label**: a single record can carry several emotions at once (or none, before it's enriched).

The six recognized emotions are:

* **Joy**
* **Anger**
* **Sadness**
* **Fear**
* **Surprise**
* **Disgust**

Where you see it:

* **Record detail drawer**, listed in the **AI enrichment** section.
* **Topics & Subtopics**, as one colored badge per detected emotion on each record card.
* **Charts**, where you can chart the count of each emotion.

<Note>
  Because emotions are a multi-label set, filter charts on a single emotion
  using the **contains** operator rather than an exact-match equals.
</Note>

## Language consolidation

Feedback often arrives in many languages, which makes it hard to read and analyze together. Language consolidation solves this in two ways.

### Translation into a common language

Every open-text answer is translated into your organization's configured target language and stored alongside the original:

* The **translated text** is shown throughout Unify Feedback in place of the original, with a **Translated to ** chip. The original text is always available in the tooltip and in the record detail drawer.
* In **Topics & Subtopics**, a **Comment language** toggle lets you switch between the original and the translated text.

This means an analyst working in English can read, cluster, and chart feedback that was originally submitted in German, French, Spanish, and more, all consolidated into one comparable language.

<Note>
  The target language is set at the service level for your organization. On
  Formbricks Cloud it is managed for you; self-hosted instances configure it in
  the Hub service. See [Formbricks Hub](/docs/unify-feedback/formbricks-hub).
</Note>

### Consolidating the same option across languages

For multiple-choice answers, Formbricks also carries a stable **Value ID**, the option's identifier from the source system (for example, a survey choice id). This lets charts group the **same option** together even when its label was captured in different languages or later edited, instead of splitting it into a separate category per localized label.

When charting choice questions, group by **Value (Option)** rather than the raw text value to keep categories consolidated across languages.

## Using enrichment in charts

All enrichment fields are available in [Dashboards & Charts](/docs/unify-feedback/dashboards-charts) as dimensions and measures. Records that haven't finished enriching are grouped under a **Not enriched** value, so you can see enrichment coverage at a glance.

## Requirements

* A Feedback Dataset with records that contain open text.
* Enrichment runs on the Formbricks Hub. No local AI provider configuration is required to read enrichment fields.

<Note>
  Unify Feedback is an enterprise feature. Enable it on Formbricks Cloud with a
  paid plan, or self-host with a license.
</Note>

# Feedback Datasets
Source: https://formbricks.com/docs/unify-feedback/feedback-datasets

Org-level containers that group related Feedback Records and their sources.

A **Feedback Dataset** is the top-level container for feedback inside an organization. Every Feedback Record belongs to exactly one dataset, and every source writes into a single dataset.

## When to create a new dataset

Create one dataset per logically separate group of feedback. Common patterns:

* **By product line** (e.g. "Mobile devices", "Web apps")
* **By stakeholder group** (e.g. "Customers", "Employees")
* **By region** (e.g. "Europe", "North America")

## Workspace access

Datasets live at the **organization** level but are exposed to **workspaces** through an access list. Each workspace can **only access one dataset.**

Manage dataset access from **Settings → Organization → Feedback Datasets**:

* Create new datasets
* Rename or archive datasets
* Add or remove workspace access

Only **Owners** and **Managers** can manage datasets. Workspace members see the datasets their workspace has access to inside the Unify section.

## Archiving

Archiving a dataset hides it from default views but does not delete its records. Use it for one-off programs that have ended.

# Feedback Records
Source: https://formbricks.com/docs/unify-feedback/feedback-records

The normalized unit of feedback inside a Feedback Dataset.

A **Feedback Record** is one piece of feedback expressed in a normalized schema. Whether it came from a survey response, a CSV row, or an API push, it lands in the same shape so you can query everything together.

## The Feedback Record schema

Every record has the following fields. Required fields must be mapped by every source.

| Field               | Type      | Required | Description                                                                                                 |
| ------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `submission_id`     | string    | Yes      | Stable ID for the submission (e.g. `response_id`, `ticket_id`, `order_id`). Used for idempotent re-imports. |
| `collected_at`      | timestamp | Yes      | When the feedback was originally collected.                                                                 |
| `source_type`       | string    | Yes      | The kind of source (e.g. `survey`, `csv`, `review`).                                                        |
| `field_id`          | string    | Yes      | Stable identifier for the question/field.                                                                   |
| `field_type`        | enum      | Yes      | One of `text`, `categorical`, `nps`, `csat`, `ces`, `rating`, `number`, `boolean`, `date`.                  |
| `tenant_id`         | string    | No       | Feedback Dataset ID. Set automatically when ingesting.                                                      |
| `source_id`         | string    | No       | Reference to the survey/form/ticket/review ID.                                                              |
| `source_name`       | string    | No       | Human-readable source name for display.                                                                     |
| `field_label`       | string    | No       | The question text or field label.                                                                           |
| `field_group_id`    | string    | No       | Groups related fields (matrix, ranking, grid questions).                                                    |
| `field_group_label` | string    | No       | Human-readable group label.                                                                                 |
| `value_text`        | string    | No       | Text responses.                                                                                             |
| `value_number`      | float64   | No       | Numeric responses (ratings, NPS, CSAT).                                                                     |
| `value_boolean`     | boolean   | No       | Yes/no responses.                                                                                           |
| `value_date`        | timestamp | No       | Date responses.                                                                                             |
| `metadata`          | jsonb     | No       | Free-form context (device, campaign, custom fields).                                                        |
| `language`          | string    | No       | ISO 639-1 language code (`en`, `de`, `fr`, ...).                                                            |
| `user_id`           | string    | No       | Anonymous user ID. Never store PII here.                                                                    |

The right `value_*` field is set based on `field_type`. For example a `nps` field uses `value_number`, an open-text comment uses `value_text`.

## Viewing and managing records

Inside a workspace, navigate to **Unify → Feedback Records**. You'll see the latest records across every dataset the workspace has access to, sorted by `collected_at`.

From the table you can:

* **Filter** by dataset, source, field type, or date range.
* **Open** a record drawer to see the full field set and metadata.
* **Edit** values inline for cleanup (e.g. relabel a categorical answer).
* **Delete** a record.
* **Add** a record manually via the "+ Add" button.

## Idempotent imports

Sources that re-ingest data (CSV uploads, API ingestions) use `submission_id` as the dedup key. Re-importing the same `submission_id` updates the existing record instead of creating a duplicate.

# Feedback Sources
Source: https://formbricks.com/docs/unify-feedback/feedback-sources

Sources that bring feedback data into a Feedback Dataset.

A **Source** defines how external data is mapped into Feedback Records inside a Feedback Dataset. Manage them from **Unify → Sources**.

## Source types

Formbricks supports three source types:

### 1. Formbricks Surveys

Pipe responses from a Formbricks survey directly into a Feedback Dataset. Pick a survey, select the questions you want to ingest - that's it. Formbricks automatically maps each question to its `field_type`. Optionally create Feedback Records of existing responses on connect.

### 2. CSV Import

Upload a CSV (up to **2 MB** and **1,000 rows**) and Formbricks auto-suggests a column mapping based on common header names (`timestamp`, `response_id`, `rating`, `feedback_text`, ...). Required columns: `submission_id`, `field_id`, `field_type`, and the feedback value.

<Note>
  Re-uploading a CSV with the same `submission_id` updates existing records instead of creating duplicates.
</Note>

A sample CSV is available from the source creation dialog.

### 3. API Ingestion

Push records into a dataset programmatically from your own systems. Best for server-to-server ingestion. API reference docs are coming soon.

## Field mapping

For CSV and API sources, you map each source column or question to a Feedback Record field. CSV mapping suggests matches automatically with high/medium/low confidence based on header names.

For Formbricks Surveys, we handle the mapping internally - each question type is translated into the matching Hub `field_type`:

* Single-select, multi-select, dropdown → `categorical`
* NPS → `nps`
* Rating → `rating`
* CSAT → `csat`
* CES → `ces`
* Free text → `text`
* Number → `number`
* Date → `date`
* Boolean / consent → `boolean`

## Managing sources

From the Sources page you can:

* **Create** a new source for any source type.
* **Edit** the mapping for an existing source.
* **Pause** or **resume** ingestion.
* **Delete** a source. Existing records stay in the dataset.

# Formbricks Hub
Source: https://formbricks.com/docs/unify-feedback/formbricks-hub

The data layer that powers Unify Feedback.

**Formbricks Hub** is Formbricks' unified feedback data layer. It stores normalized feedback from multiple input channels so teams can query, analyze, and act on it in one place.

Unify Feedback is powered by Hub under the hood: Feedback Sources ingest data into Hub, Feedback Records are stored in Hub, and dashboards, charts, and topics build on that shared model.

Hub is built for **the age of AI**: each open-text feedback record is vectorized so semantic search, clustering, and retrieval work out of the box. Its event-based architecture also lets you enrich records with any model, provider, and custom metadata of your choice.

The Hub is fully open-source (Apache 2.0) and can be self-hosted.

To learn more, visit the Hub docs at [hub.formbricks.com](https://hub.formbricks.com) and the [Hub API Reference](https://hub.formbricks.com/api).

# Close the Loop and Assign Journey Owners
Source: https://formbricks.com/docs/unify-feedback/journey-management/close-the-loop

Route journey signals to a journey owner, track each case to recovery, and keep journeys owned over time.

Route journey signals to a journey owner, track each case through closed-loop tracking, and keep journeys owned over time.

## Purpose

A signal changes a journey only when it leads to action. Closed-loop tracking records what was done and whether the customer recovered; a journey owner stays accountable for the journey's end-to-end performance. Together they keep journeys from decaying into static artifacts. It lets you:

* Get each detection signal to the person who can act on it
* Turn a pattern register into tracked outer loop tickets
* Record both what customers said and what was done (closed-loop tracking)
* Keep every journey under an owner with a review cadence (journey governance)

## Formbricks Approach

* [Webhooks](/docs/platform/features/integrations/webhooks) to push signals into your warehouse, journey tool, or a custom service
* [Native integrations](/docs/platform/features/integrations/overview) to route into Slack, a CRM, or an issue tracker with no code
* [Feedback Records](/docs/unify-feedback/feedback-records) to log the action taken and the recovery outcome
* [Feedback Datasets](/docs/unify-feedback/feedback-datasets) per journey so the journey owner has one place to review

# Capture Detection Signals at the Moments That Matter
Source: https://formbricks.com/docs/unify-feedback/journey-management/detection-signals

Collect feedback at the few journey steps that decide retention, and route it in as a detection signal to act on.

Collect feedback at the few journey steps that decide the outcome, and route it in as a detection signal for the inner loop.

## Purpose

Journey Activation runs on two loops. The inner loop opens a case to recover one customer in trouble; the outer loop fixes the recurring problem behind many cases. Both start with a detection signal: a feedback, behavioral, or operational trigger that flags a customer who needs attention. Surveys are a strong feedback signal at the moments that matter, the few steps where a journey is won or lost. It lets you:

* Catch problems at the steps that decide the journey outcome
* Open inner loop cases while the experience is fresh
* Feed both inner loop recovery and outer loop pattern detection
* Avoid surveying steps that do not change the result

## Formbricks Approach

* [Actions](/docs/surveys/website-app-surveys/actions) to trigger a survey on the exact behavior that defines the moment
* [Attribute-based targeting](/docs/surveys/website-app-surveys/attribute-based-targeting) to fire for the right segment
* [Recontact options](/docs/surveys/website-app-surveys/recontact) to cap contact frequency, set once at the workspace level
* [Feedback Datasets](/docs/unify-feedback/feedback-datasets) and [Sources](/docs/unify-feedback/feedback-sources) to land the signal next to the journey's other data

For a custom moment, fire the action from your code, then attach a survey to it:

```javascript theme={null}
formbricks.track("setup_abandoned");
```

# Build Journey Performance Scorecards
Source: https://formbricks.com/docs/unify-feedback/journey-management/journey-scorecards

Turn journey-tagged feedback into one health score per journey using Unify Feedback dashboards.

Turn journey-tagged feedback into a Journey Performance Scorecard for each journey using Unify Feedback dashboards.

## Purpose

A Journey Performance Scorecard tracks completion, duration, effort, satisfaction, and the business outcome for one journey, measured as an end-to-end experience. Feedback supplies the experience metrics; the rest come from behavioral and operational data. A scorecard per journey lets you:

* Compare journeys and prioritize the ones that need work
* Track one experience metric per journey consistently over time
* See which journey stage drags the score down
* Hold experience, behavioral, and business signals in one view

## Formbricks Approach

* [Feedback Records](/docs/unify-feedback/feedback-records) tagged by journey and stage as the data
* [Dashboards & Charts](/docs/unify-feedback/dashboards-charts) to chart one experience metric per journey: CES for onboarding, CSAT for support, NPS for renewal
* [Feedback Sources](/docs/unify-feedback/feedback-sources) (CSV or API) to add completion, duration, and other behavioral signals
* [Webhooks](/docs/platform/features/integrations/webhooks) to feed the same records into Qualtrics, Medallia, or your own journey tool

# Map Feedback to Journeys, Not Touchpoints
Source: https://formbricks.com/docs/unify-feedback/journey-management/map-feedback-to-journeys

Tag feedback by journey and stage so it rolls up to end-to-end journeys instead of scattered screens.

Tag feedback by journey and stage so it rolls up into end-to-end journeys instead of scattered touchpoints.

## Purpose

Journey Management measures and improves each customer journey end to end, rather than tracking touchpoints in isolation. Feedback is one input, alongside behavioral and operational data. Tagging each response with its journey and stage is what lets you stitch it into a single journey instance. It lets you:

* See which journey a problem affects, and at which journey stage
* Group responses into end-to-end journeys, not single screens
* Line feedback up with behavioral and operational data for journey stitching
* Give journey scorecards and pattern analysis a clean base to build on

## Formbricks Approach

* [Feedback Datasets](/docs/unify-feedback/feedback-datasets) to hold one journey or program
* [Feedback Records](/docs/unify-feedback/feedback-records) tagged with journey and stage
* [Hidden Fields](/docs/surveys/general-features/hidden-fields) to pass journey and stage into a link survey at collection time

Pass the journey and stage as Hidden Fields so each record arrives pre-tagged:

```
https://app.formbricks.com/s/<surveyId>?journey=onboarding&stage=activation&userId=123
```

Keep journey and stage names identical across Formbricks, your warehouse, and your journey tool so the data lines up. Survey setup is covered in the [Surveys docs](/docs/surveys/best-practices/understanding-survey-types).

# Surface Recurring Patterns with Topics
Source: https://formbricks.com/docs/unify-feedback/journey-management/recurring-patterns

Cluster open-text feedback by journey into a pattern register the outer loop can fix at the root.

Cluster open-text feedback by journey to turn one-off complaints into a pattern register the outer loop can act on.

## Purpose

Inner loop actioning resolves issues one customer at a time. Outer loop actioning finds the recurring journey issues behind them and changes the root cause. A score shows a journey is underperforming but not why; clustering open-text feedback by journey supplies the why. It lets you:

* Turn scattered responses into named, recurring journey issues
* See which journey stage a problem concentrates in
* Build a pattern register: a shortlist of systemic issues worth a root-cause fix
* Back each pattern with customers' own words

## Formbricks Approach

* An open follow-up question on every rating to capture the reason behind the score
* [Topics & Subtopics](/docs/unify-feedback/topics-subtopics) to cluster open-text [Feedback Records](/docs/unify-feedback/feedback-records) into themes
* [Feedback Datasets](/docs/unify-feedback/feedback-datasets) to keep clustering scoped to one journey

Promote a theme that recurs at the same stage to the pattern register with its stage and rough volume, then hand it to the outer loop for root-cause work.

# Unify Feedback
Source: https://formbricks.com/docs/unify-feedback/overview

Bring feedback from any source to Formbricks and turn it into insights.

Unify Feedback is the part of Formbricks that consolidates feedback from across your stack into a single, queryable store. Survey responses, CSV imports, API ingestions, and tool-generated records all land in the same model so you can analyze them together.

## Why Unify Feedback

Most companies collect feedback in many places: surveys, support tickets, app store reviews, NPS tools, sales calls. Each lives in its own silo with its own schema. Unify Feedback normalizes all of these into **Feedback Records** grouped under **Feedback Datasets**, so they can be filtered, visualized, and acted on together.

## How it works

1. **Create a Feedback Dataset.** A dataset is a tenant-scoped bucket for related feedback (for example, "Product Feedback" or "Support 2026").
2. **Connect Sources.** Pull data from Formbricks surveys, upload CSVs, or push records via the API.
3. **Explore Records.** Browse, filter, edit, and tag individual Feedback Records.
4. **Enrich.** Open-text feedback is automatically enriched with sentiment, emotions, and a consolidated language.
5. **Discover Topics.** Use vector-based Topics & Subtopics (Preview) to cluster open-text feedback.
6. **Visualize.** Build Charts and group them on Dashboards to share insights with your team.

<CardGroup>
  <Card title="Feedback Datasets" icon="folder-tree" href="/unify-feedback/feedback-datasets">
    Org-level buckets that group your feedback.
  </Card>

<Card title="Feedback Records" icon="list-check" href="/unify-feedback/feedback-records">
    The normalized unit of feedback inside a dataset.
  </Card>

<Card title="Feedback Sources" icon="plug" href="/unify-feedback/feedback-sources">
    Connectors that bring data into a dataset.
  </Card>

<Card title="Enrichment" icon="sparkles" href="/unify-feedback/enrichment">
    Sentiment, emotions, and language consolidation on open text.
  </Card>

<Card title="Dashboards & Charts" icon="chart-line" href="/unify-feedback/dashboards-charts">
    Visualize and share feedback insights.
  </Card>
</CardGroup>

<Note>
  Unify Feedback is an enterprise feature. Enable it on Formbricks Cloud with a paid plan, or self-host with a license.
</Note>

# Topics & Subtopics (Preview)
Source: https://formbricks.com/docs/unify-feedback/topics-subtopics

Vector clustering of open-text feedback into Topics and Subtopics.

<Warning>
  Topics & Subtopics is a **Preview** feature. The schema and UI may change.
</Warning>

Open-text feedback ("Why did you give this score?", support tickets, app reviews) is rich but hard to count. Topics & Subtopics uses AI to cluster free text into a two-level taxonomy you can filter, count, and trend over time.

## How it works

1. Pick a Feedback Dataset under **Unify → Topics & Subtopics**.
2. Formbricks scans `value_text` across the dataset and proposes a set of **Topics** (broad categories) and **Subtopics** (specific themes within a topic).
3. Each record can be assigned to one Topic and one Subtopic.

## What you can do today

* **Browse** the proposed Topic / Subtopic tree for a dataset.
* **Inspect** which records cluster under each Topic.

## Roadmap

* Manual edits to topic labels and assignments.
* Topic filters on Charts and Dashboards.
* Per-source topic confidence scoring.

## Requirements

* A Feedback Dataset with records.
* Smart functionality (AI) enabled at the organization level. See [AI Features](/docs/platform/features/ai-features).

# Build a workflow
Source: https://formbricks.com/docs/workflows/build

Choose and configure a workflow trigger and action, check the workflow, and enable it.

Use the workflow builder to combine a trigger with the actions it should run. This guide uses the currently
available **Response completed** trigger and **Send email** action as examples. The builder lists the options
available in your Formbricks version. Changes to draft and disabled workflows are saved automatically.

## Before you begin

You need write or manage access to the workspace. For the **Response completed** example, you also need a
survey in the same workspace as the workflow.

If you use **Send email** and the message should go to an address collected from a response, configure at
least one compatible recipient source in the survey, such as an email question, contact information, email
verification, or a hidden field.

## Create a workflow

<Steps>
  <Step title="Open Workflows">
    Select **Workflows** in the workspace navigation, then select **New workflow**. Formbricks creates a
    draft and opens the builder. Rename the workflow using the title at the top of the page.
  </Step>

<Step title="Add a trigger">
    Select **Add trigger**, then choose a trigger from the list, such as **Response completed**. Select the
    trigger card to open its configuration.
  </Step>

<Step title="Add an action">
    Select the **+** below the trigger, then choose an action from the list, such as **Send email**. Select the
    action card to open its configuration.
  </Step>
</Steps>

## Configure the Response completed trigger

If you choose the **Response completed** trigger, select the survey whose completed responses should start
the workflow. Changing the linked survey clears any ending card and email recipient configuration that
belonged to the previous survey.

Under **Ending cards**, choose one of these scopes:

* **All endings** runs the workflow for every completed response, including ending cards added later.
* **Specific endings** runs it only when the respondent reaches one of the selected ending cards.

## Configure the Send email action

If you choose the **Send email** action, complete these fields in its configuration panel:

| Field        | Configuration                                                                         |
| ------------ | ------------------------------------------------------------------------------------- |
| **Send to**  | Select one recipient source from the linked survey or workspace.                      |
| **From**     | Shows the deployment sender address. This value is read-only in the workflow builder. |
| **Reply to** | Enter one or more addresses that should receive replies.                              |
| **Subject**  | Enter the email subject.                                                              |
| **Body**     | Write the message and insert survey recall values where needed.                       |

The **Send to** options can include:

* The verified email address, when email verification is enabled for the survey
* An Open Text question configured for email input
* The email field of a Contact Info question
* A hidden field
* A workspace member, including yourself

### Personalize the body

Type `@` in the **Body** editor to insert recall values from the linked survey. You can recall answers,
variables, and hidden fields to personalize the message for each run. Learn more about the available sources
in [Recall Data](/docs/surveys/general-features/recall).

### Include response data

Turn on **Attach response data** to include the triggering survey response with the email. You can then also
turn on **Include variables** and **Include hidden fields**.

## Check validity or enable

The status button in the upper-left corner shows whether the editor's client-side checks consider the
workflow **Valid** or **Invalid**. Select it whenever you want Formbricks to manually verify that the current
workflow definition is valid and executable. For the **Response completed** example, the manual check also
confirms that required configuration is present and that the linked survey and selected ending cards still
exist.

<Note>
  Running the manual check is optional and side-effect-free. It does not create a run or execute an action. It
  is available for draft, enabled, and disabled workflows, but not archived workflows, and it requires
  workspace write access.
</Note>

You do not have to run the manual check before enabling. Open the status menu and select **Enable** when you
are ready to start the workflow. An enabled workflow listens for its configured trigger. Its definition is
read-only while enabled; select **Disable** before editing it again.

<Note>
  Enabling verifies that the workflow is executable. A workflow with incomplete or outdated configuration
  cannot be enabled.
</Note>

# Manage and monitor workflows
Source: https://formbricks.com/docs/workflows/manage-and-monitor

Manage workflow statuses, duplicate or delete workflows, and inspect runs and step logs.

Use workflow statuses to control when automations run and use run history to investigate every execution.

## Manage the lifecycle

Use the status menu in the builder to enable, disable, archive, or unarchive a workflow. You can also archive
or unarchive it from the options menu in the Workflows list.

| Status       | Behavior                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Draft**    | Editable and not running. New workflows and unarchived workflows use this status.                                  |
| **Enabled**  | Runs when its configured trigger fires and its conditions match. The definition is read-only until you disable it. |
| **Disabled** | Stops starting new runs and can be edited and enabled again.                                                       |
| **Archived** | Disabled, read-only, and hidden from the default list. It can be unarchived.                                       |

### Find and restore archived workflows

Archived workflows are excluded from the Workflows list by default. Open the **Status** filter and select
**Archived** to show them. Select **Unarchive** to restore an archived workflow as a draft.

### Duplicate a workflow

Select **Duplicate** from a workflow's options menu to create a draft copy of its definition. The copy does
not inherit the source workflow's run history.

### Delete a workflow

The **Delete** action appears after a workflow is archived.

<Warning>
  Deleting a workflow permanently removes the workflow and all of its run history. This cannot be undone.
</Warning>

## Monitor runs

There are two ways to inspect runs:

* Select **Workflows** > **Runs** to see runs across the workspace. This view includes the workflow name.
* Open a workflow and select **Runs** to see only executions of that workflow.

Each table row shows the trigger, run status, start time, and finish time. Select a row to open its details.

### Run statuses

| Status        | Meaning                                     |
| ------------- | ------------------------------------------- |
| **Queued**    | The run is waiting to start.                |
| **Running**   | The workflow is currently executing.        |
| **Completed** | All required steps finished successfully.   |
| **Failed**    | The workflow could not finish successfully. |
| **Canceled**  | The run stopped before it completed.        |

### Inspect run details and logs

The run details drawer includes:

* Run ID, status, start and finish times, attempt number, and any run-level error
* A chronological list of step logs, including duration, input, output, and errors
* The trigger payload and accumulated run data
* A link back to the workflow

Each step log has its own status: **Pending**, **Running**, **Succeeded**, **Failed**, or **Skipped**. A failed
step includes its error to help you identify the configuration or delivery problem.

## Permissions

| Workspace access    | Available workflow operations                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Read-only**       | List and open workflows, inspect their configuration, and view workspace-wide or workflow-specific runs.                       |
| **Write or manage** | Create, configure, validate, enable, disable, archive, unarchive, duplicate, and delete workflows, in addition to read access. |

Workflow status still limits editing for members with write or manage access: enabled and archived definitions
are read-only. Disable an enabled workflow or unarchive an archived workflow before changing its definition.

# Workflows
Source: https://formbricks.com/docs/workflows/overview

Automate response-driven tasks in Formbricks with triggers, filters, actions, and observable runs.

Workflows automate tasks in response to events in Formbricks. You define the event that starts the workflow,
narrow down which events qualify, and choose the action Formbricks should perform.

<Note>Workflows are part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license).</Note>

## How Workflows work

<CardGroup>
  <Card title="Trigger" icon="bolt">
    The event that starts a workflow. The currently available trigger is **Response completed** for a
    survey linked to the workflow.
  </Card>

<Card title="Condition or filter" icon="filter">
    A rule that gates execution. You can currently filter completed responses by the ending card the respondent
    reached.
  </Card>

<Card title="Action" icon="play">
    What the workflow does after its trigger and filter match. The currently available action is **Send email**.
  </Card>

<Card title="Run" icon="list-check">
    A concrete execution of an enabled workflow. Every run records its overall status and logs for its
    individual steps.
  </Card>
</CardGroup>

For example, a workflow using the currently available trigger and action can follow this sequence:

`Response completed trigger` → `optional ending card filter` → `Send email action`

## Available triggers, conditions, and actions

The builder lists the options available in your Formbricks version. The tables below show what you can use
today.

### Triggers

| Trigger                | Description                                                                  |
| ---------------------- | ---------------------------------------------------------------------------- |
| **Response completed** | Starts the workflow when a survey linked to it records a completed response. |

### Conditions

| Condition              | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| **Ending card filter** | Runs the workflow for all ending cards or only the selected ones of the survey. |

### Actions

| Action         | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| **Send email** | Sends a personalized email using data from the triggering response. |

## Current capabilities

You can currently use Workflows to:

* Start when a response is completed for a selected survey
* Run for all ending cards or only selected ending cards
* Send a personalized email using survey response data
* Inspect workspace-wide or workflow-specific execution history

<Note>
  The available options currently include the **Response completed** trigger, its optional ending card filter,
  and the **Send email** action. User-authored condition nodes, branching, webhooks, schedules, delays, and
  loops are not available yet.
</Note>

## Get started

<CardGroup>
  <Card title="Build a workflow" icon="rocket" href="/workflows/build">
    Choose a trigger and action, configure them, optionally validate the workflow, and enable it.
  </Card>

<Card title="Manage and monitor" icon="magnifying-glass-chart" href="/workflows/manage-and-monitor">
    Manage the workflow lifecycle and investigate runs and step logs.
  </Card>
</CardGroup>

## Self-host Workflows

Self-hosted deployments run Workflows through the shared Redis-backed Job Runner built into the Formbricks web
process. Before using Workflows in production, configure Redis and any services required by your actions, such
as SMTP for **Send email**.

<Card title="Configure the Job Runner" icon="gears" href="/self-hosting/configuration/job-runner">
  Set up the runner, scale it across replicas, and troubleshoot queued or failed runs.
</Card>