Endpoint for creating or identifying a user within the specified environment. If the user already exists, this will identify them and potentially update user attributes. If they don't exist, it will create a new user.


Create or Identify User

Documentation - Formbricks

Introduction

Get to know Formbricks and its capabilities.

What is Formbricks?

Open-source Experience Management. Free & open source.

Open-Source

Learn how Formbricks helps you gather, analyse, and report experience data.

XM & Surveys

Assign different roles to organization members to grant them specific rights like creating surveys, viewing responses, or managing organization members.

User Management

Keep the survey styling consistent over all surveys with a Styling Theme. Customize the colors, fonts, and other styling options to match your brand's aesthetic.

Styling Theme

Branding the emails that are sent to your respondents.

Email Branding

Each project on Formbricks has two environments: a test environment and a production environment. The test environment is used to test your surveys through before they are sent out to your customers.

Test Environment

Self-Hosting

How to set up Formbricks instance with a one-click script

One-Click Setup

Set up Formbricks quickly using our ready-to-use Docker image.

Docker Setup

Monitoring your Formbricks installation for optimal performance.

Monitoring

How to set up Formbricks in a High-Availability Cluster

Cluster Setup

Deploy the new Helm chart on a Kubernetes cluster using Helm.

Kubernetes Deployment

Using Formbricks One-Click Setup with a Custom SSL Certificate.

Custom SSL Certificate

Environment Variables

Set up email functionality for your self-hosted Formbricks instance

SMTP Configuration

Domain Configuration

Migration

License

How to activate your Formbricks Enterprise License

License Activation

Rate Limiting

Learn how to setup formbricks locally and build custom integrations and services.

Overview

How to set up Formbricks on a Linux machine

Linux

How to set up Formbricks on a Mac machine

How to set up Formbricks on a Windows machine

Windows

How to set up Formbricks in a Gitpod workspace

Gitpod

How to set up Formbricks in a GitHub Codespaces environment

GitHub Codespaces

High-level architecture and technical details of the Formbricks platform

Solution Overview

Overview of the Formbricks database schema and relationships

Database Model

How Formbricks handles tenant separation on Formbricks Cloud

Tenant Separation

Contribute to Formbricks

Here, you'll find help with common issues.

Troubleshooting

 Formbricks provides two APIs: the Public Client API for frontend survey interactions and the Management API for backend management tasks.

REST API

Here is how you can generate an API key which gives you full access to the Formbricks Management API. Keep it safe!

Generate API Key

Here is how you can test your API key to make sure it is working.

Test API Key

Update a contact's attributes in Formbricks to keep them in sync with your app or when you want to set a custom attribute in Formbricks.

Update Contact (Attributes)

Retrieves a contact's state including their segments, displays, responses and other tracking information. If the contact doesn't exist, it will be created.

Get Contact State

Create a new display for a valid survey ID. If a userId is passed, the display is linked to the user.

Create Display

Update an Display for a user. A use case can be when a user submits a response & you want to link it to an existing display.

Update Display

Retrieves the environment state to be used in Formbricks SDKs **Cache Behavior**: This endpoint uses server-side caching with a **5-minute TTL (Time To Live)**. Any changes to surveys, action classes, project settings, or other environment data will take up to 5 minutes to reflect in the API response. This caching is implemented to improve performance for high-frequency SDK requests.

Get Environment State

Create a response for a survey and it's fields with the user's responses. The userId & meta here is optional

Create Response

Update an existing response for example when you want to mark a response as finished or you want to change an existing response's value.

Update Response

Fetches all the action classes available in the environment

Get All Action Classes

Create Action Class from the UI or from the API! You can read more about them [here](https://formbricks.com/docs/in-app-surveys/actions).

Create Action Class

Get Action Class by ID

Delete Action Class

Fetches all the available attribute classes

Get All Attribute Classes

Create a new Attribute Class by passing in its type as well as the name! Now just use them in your app and pass this value with a user & it'll be associated with it.

Create Attribute Class

Get Attribute Class by ID

Delete an attribute class by its ID. Please note that you currently cannot delete the "automatic" type of attributes. Please ignore them if you do not wish to utilise them.

Delete Attribute Class

Retrieve a list of all contact attribute keys defined in the current environment

Get All Contact Attribute Keys

Retrieve a specific contact attribute key by its ID. This returns detailed information about how a particular attribute is defined in your environment.

Get Contact Attribute Key by ID

Retrieve a list of all contact attributes in the current environment

Get All Contact Attributes

Retrieve a list of all contacts for the current environment

Get All Contacts

Get Contact by ID

Fetches the product associated with the passed API key

Get all the identified people from Formbricks

Get All Persons

Get a person by their internal ID on Formbricks. This internal ID can be found from the Get All Person endpoint.

Get Person by ID

Delete an identified person from Formbricks.

Delete Person

Pass the surveyId as a Query Parameter & only fetch responses for a specific survey that you have access to.

Get Survey Responses

Create a user response using the management API

Fetch the entire response object based on its ID

Get Response by ID

Update an existing user response with new data

Delete Response

API endpoint for uploading public files. Uploaded files are public and accessible by anyone. This endpoint requires authentication. It accepts a JSON body with fileName, fileType, environmentId, and optionally allowedFileExtensions to restrict file types. On success, it returns a signed URL for uploading the file to S3 along with a local upload URL.

Upload Public File

Management API endpoint for uploading public files to local storage. This endpoint requires authentication. File metadata is provided via headers (X-File-Type, X-File-Name, X-Environment-ID, X-Signature, X-UUID, X-Timestamp) and the file is provided as a multipart/form-data file field named "file". The "Content-Type" header must be set to a valid MIME type.

Upload Public File to Local Storage

Get All Surveys

Create a survey with granular settings, questions, their types, welcomeCard, thankYouCard, languages, etc right from this API. We'd however recommend you to do this via our Formbricks App with the UI for a better visual experience.

Create Survey

Get Survey by ID

Update an existing survey with new properties. This is also what we'd recommend you to do from the UI for a better visual feedback.

Update Survey

Delete a Survey by its ID. Please use this only when extrememly necessary.

Delete Survey

Generates multiple single use survey links for a survey based on its id.

Get SingleUse Links

Retrieve a list of all webhooks for the current environment

Get All Webhooks

Create a new webhook right from the API and see it active right away!

Create Webhook

Get a specific webhook object based on its ID

Get Webhook

Delete an existing webhook by provifding it's ID. It will immediately apply and not trigger again.

Delete Webhook

Formbricks' Health Check endpoint to make sure the App & the Database are connected with each other & up!

Health Check

API v2 Reference (Beta)

Create a response for a survey and its fields with the user's responses. The userId & meta here is optional

Retrieves the environment state to be used in Formbricks SDKs. **Cache Behavior**: This endpoint uses server-side caching with a **5-minute TTL (Time To Live)**. Any changes to surveys, action classes, project settings, or other environment data will take up to 5 minutes to reflect in the API response. This caching is implemented to improve performance for high-frequency SDK requests.

Endpoint for creating or identifying a user within the specified environment. If the user already exists, this will identify them and potentially update user attributes. If they don't exist, it will create a new user.

API endpoint for uploading private files. Uploaded files are kept private so that only users with access to the specified environment can retrieve them. The endpoint validates the survey ID, file name, and file type from the request body, and returns a signed URL for S3 uploads along with a local upload URL.

Upload Private File

API endpoint for uploading private files to local storage. The request must include a valid signature, UUID, and timestamp to verify the upload. The file is provided as a Base64 encoded string in the request body. The "Content-Type" header must be set to a valid MIME type, and the file data must be a valid file object (buffer).

Upload Private File to Local Storage

Get roles

Fetches the projects and organizations associated with the API key.

Get responses

Create a response

Get a response

Update a response

Delete a response

Uploads contacts in bulk. Each contact in the payload must have an 'email' attribute present in their attributes array. The email attribute is mandatory and must be a valid email format. Without a valid email, the contact will be skipped during processing.

Upload Bulk Contacts

Gets contact attribute keys from the database.

Get contact attribute keys

Creates a contact attribute key in the database.

Create a contact attribute key

Gets a contact attribute key from the database.

Get a contact attribute key

Updates a contact attribute key in the database.

Update a contact attribute key

Deletes a contact attribute key from the database.

Delete a contact attribute key

Retrieves a personalized link for a specific survey.

Get personalized survey link for a contact

Generates personalized survey links for contacts in a segment.

Get survey links for contacts in a segment

Get webhooks

Create a webhook

Get a webhook

Update a webhook

Delete a webhook

Get teams

Create a team

Get a team

Update a team

Delete a team

Get project teams

Update a project team

Create a projectTeam

Deletes a project team from the database.

Delete a project team

Gets users from the database.<br />Only available for self-hosted Formbricks.

Get users

Create a new user in the database.<br />Only available for self-hosted Formbricks.

Create a user

Updates an existing user in the database.<br />Only available for self-hosted Formbricks.

Update a user

Self Hosting

Development

API v1 Reference

Go to app

Support

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

Add Image / Video

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

API v1 Documentation

Client API - Contacts

Client API - Display

Client API - Environment

Client API - Response

Client API - User

Management API - Action Class

Management API - Attribute Class

Management API - Contact Attribute Keys

Management API - Contact Attributes

Management API - Contacts

Management API - Me

Management API - People

Management API - Response

Management API - Storage

Management API - Survey

Management API - Webhook

Health

Create or Identify User

Path Parameters

Body

Response