Skip to main content
A Formbricks file (.formbricks.json) is a survey written as JSON. You can edit it in any text editor, or hand it to an AI assistant such as ChatGPT or Claude, then import it back. It’s the way to iterate on a survey with an assistant that isn’t connected to Formbricks.
1

Export the survey

On the survey’s card, open ⋮ → Export → Formbricks file (.json). See Import & Export.
2

Edit the file

Change it by hand, or give it to your assistant along with this page and the JSON Schema.
3

Import it

Go to Surveys → New Survey → Import survey and drop the file. In the workspace the survey came from, choose Update to change it in place, or Create a new survey for a copy.
An invalid file creates nothing, so you can fix it and try again as often as you need. A file you have already used for an Update keeps working: the dialog tells you the survey changed since the export and offers Update anyway.

The envelope

Every file has four keys at the top:
format is the file format’s own version, separate from the Formbricks version. Formbricks reads every format up to its own and refuses newer ones.

The JSON Schema

Every file names its JSON Schema in $schema: https://formbricks.com/docs/schemas/formbricks-file/v1.json It describes every key the format allows, every question type and the fields each one needs. Editors such as VS Code use it to check the file as you type. Give the address to an AI assistant and it can check its own output before you import. The schema can’t express every rule. The import also checks that logic and recall point at questions, variables and hidden fields that exist, that every text is in every language the survey declares, and that IDs are unique. Each problem it finds names the field, so you know where to look.

What you can edit

Anything under survey. Some rules keep the file importable:
  • Texts are objects keyed by language code: { "en-US": "…", "de-DE": "…" }. Give each text in every language listed in languages, and use no other codes.
  • IDs. Keep the IDs of what you don’t change: logic, recall and existing responses point at them. A new question needs its own ID, unique in the survey, made of letters, numbers, - and _. A new block needs an ID of lowercase letters and numbers.
  • Codes. Questions and options carry the code the survey gave them, which exports use. Once a survey has left draft, an Update can’t change a code, a question’s type or an option’s text, and can’t remove an option.
  • Logic and recall point at questions by ID. Logic can only check a question in the same or an earlier block, and recall can only use a question shown before it.
  • Show-ifs and rules before the first question. A block, question or option shows only when its showIf matches, and startLogic holds the rules that run before the first question. Both follow the rules of logic; a rule before the first question can’t read an answer, since nothing is answered yet.
  • Embedded Data. embeddedFields lists every hidden field, variable and calculated field with its type; a calculated date field is only there, not in variables. hiddenFields and variables are the older form of the same list: change embeddedFields with them, or the import refuses the file and names each field that disagrees. Create new skips this check for an empty variables list or an empty hiddenFields.fieldIds list, so a field you remove from that list alone stays in the survey. Update checks empty lists too. A shared field carries its library key: it links to the target workspace’s field with the same key, source and type, or else becomes a field of the survey’s own.
  • Triggers (app surveys) point at an action by its ID in references.actionClasses. Add the action there when you add a trigger.
  • Targeting filters that name a contact attribute need that attribute in references.attributeKeys. An attribute the workspace doesn’t have yet is created, so its key must be lowercase letters, numbers and underscores, starting with a letter, and not one Formbricks reserves (user_id, first_name, last_name).
  • name is used for a new survey, with “(imported)” added. An Update keeps the survey’s own name.
  • status is ignored. An import always creates a draft, and an Update keeps the survey’s status.
Leave formbricks as it was exported. source.surveyId is how Formbricks finds the survey to update, and source.updatedAt is how it notices the survey changed after the export. Changing it doesn’t make the file a new survey by itself: if it matches another survey in the workspace, the import offers to update that one. For a new survey, use an ID that matches none, or choose Create new when the import finds a match, and check which survey a match names before you choose Update. Keys the format doesn’t know are dropped with a warning each in the import report, so a key an assistant invents doesn’t block the import. A file exported before the share preview was left out still carries survey.metadata: it is dropped the same way, with one warning, and never written to a survey.

Writing a file from scratch

You can write a file without exporting one first. It needs the whole formbricks part, with format set to 1 and a source whose IDs are made of lowercase letters and numbers. Use made-up IDs: a surveyId that matches no survey in the workspace makes the import create a new survey. The quickest start is to export any survey and replace its content.

What Update replaces

Update replaces the survey’s:
  • questions, blocks and endings, and the welcome card;
  • languages and translations, and the language switch settings;
  • hidden fields, variables and calculated fields (embeddedFields);
  • logic, the rules before the first question, show-ifs and targeting;
  • triggers, only when Use the file’s triggers is ticked.
A file without a startLogic key, such as one exported before the flow editor, keeps the survey’s rules before the first question. To remove them, add "startLogic": [] to the file. It keeps the survey’s ID, name, status, responses, display and link settings, styling and other settings. It never updates an active survey. See Update a survey from a file for the choices the dialog offers. Two parts of the file must match the survey: its type (link or app) and its defaultLanguage. To change either, import the file as a new survey.

Common errors

When a file has problems, the dialog says This Formbricks file has problems. Fix them and import it again: and lists up to ten of them, each as the field and the reason. Fields are named from the top of the file: file.survey.blocks.0.elements.1.headline is the headline of the second question in the first block. Nothing is created until every problem is fixed. Behind the dialog, the import answers with an RFC 9457 problem whose code is formbricks_file_invalid. Each entry of its invalid_params has the field’s name, the reason, and often a code: Other messages the dialog shows for a Formbricks file: