Headless Surveys

​

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. 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:

POST /api/v1/management/surveys
Headers:
  x-api-key: <your-api-key>
  Content-Type: application/json

Body:
{
  "environmentId": "your-environment-id",
  "type": "link",
  "name": "Customer Feedback Survey",
  "questions": [
    ...
  ]
}

​

Fetch Survey Schema:

​

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

​

Implementation Options:

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

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

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

GET /api/v1/client/{environmentId}/environment
Headers:
  Content-Type: application/json

Body:
{
  "data": {
    "actionClasses": [
      { ... },
      { ... }
    ],
    "project": {
      "id": "<project_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:

• 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 /api/v1/client/{environmentId}/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):

​

Consume Analytics & Response Data:

​

Option A: Real-time Webhooks (Recommended):

1. Go to Formbricks Settings → Webhooks
2. Add your endpoint URL: https://your-domain.com/webhooks/formbricks
3. Select triggers:
   • responseCreated - New response started
   • responseUpdated - Response in progress
   • responseFinished - Response completed

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

​

Option B: Pull from API on Demand:

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