🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Formbricks Premium Add-on Setup Guide

Updated 8 min read Gravity Forms Integrations A–Z
On this page
  1. Video walkthrough
  2. What you need
  3. Create a Formbricks API key
  4. The settings page
  5. Create a feed
  6. Formbricks contact
  7. Survey response
  8. What happens on submit
  9. Retries never create duplicates
  10. Notifications and merge tags
  11. Errors and troubleshooting
  12. Privacy and security
  13. For developers
  14. Frequently asked questions
  15. Does it work with self-hosted Formbricks?
  16. Can one form write to two workspaces?
  17. Do I need a survey?
  18. What if Formbricks is down when a form is sent?

Video walkthrough

Gravity Forms Formbricks Add-On Setup Guide: Contacts & Survey Responses (WordPress Side)
Video setup guide: Gravity Forms Formbricks Watch on YouTube

The Gravity Forms Formbricks Premium Add-on connects your WordPress forms to Formbricks, the open-source survey and experience management platform. When someone submits a form, the add-on creates or updates a Formbricks contact with the email, user ID, name and any attributes you map from your fields, and it can also record the answers as a response of a Formbricks survey. Your research and product teams then see form feedback next to every in-app and link survey, in one place, tied to the same person.

It works with Formbricks Cloud and with a self-hosted Formbricks on your own server. You enter the address of your Formbricks and an API key; the key is stored encrypted, and the add-on only ever contacts the Formbricks address you set. This guide walks through the setup, every feed option, how retries work and what happens when something goes wrong.

What you need

  • WordPress with Gravity Forms 2.9 or newer.
  • PHP 7.4 or newer.
  • An active license key for this add-on.
  • A Formbricks organization on Formbricks Cloud, or a self-hosted Formbricks with contacts enabled.
  • An organization API key with write access to the workspace (project) your contacts should go to.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else, so a form is never left half connected. Contacts and attributes are a Formbricks feature: on Formbricks Cloud they are part of your plan, and a self-hosted instance needs contacts turned on. If they are not available, Formbricks answers with a clear message and the add-on writes it on the entry.

Create a Formbricks API key

  1. Log in to Formbricks and open Organization settings, then API Keys.
  2. Click Add API key, give it a label such as “WordPress forms”, and add the workspace (project) you want to use with write permission. Add more workspaces if different forms should write to different ones.
  3. Copy the key. Formbricks shows it only once.

The add-on sends the key in the x-api-key header that the Formbricks Management API expects, never in an address. A key with only read permission can list workspaces but cannot save contacts; Test connection tells you when that is the case.

The settings page

Go to Forms → Settings → Formbricks. Activate your license key first; the connection settings appear once the license is valid.

  • Formbricks address. https://app.formbricks.com for Formbricks Cloud, or the address of your own Formbricks, for example https://surveys.yourcompany.com. A Formbricks served from a sub-folder or a custom port works too. If you paste an API address ending in /api/v1 or /api/v2, the add-on keeps only the root.
  • API key. The key from Formbricks. It is encrypted with the salts of your site before it is saved, and the field never shows it again. You can also define it in wp-config.php with the GFFB_API_KEY constant; the field is then hidden.
  • Default workspace. The workspace contacts and responses go to. The list is filled by Test connection.
  • Test connection. Uses what is typed on the screen, asks Formbricks which workspaces the key may use, fills the workspace list and confirms the chosen workspace. Save the settings afterwards.
The Formbricks settings page in Gravity Forms: license key, Formbricks address, API key, default workspace selector and a Test connection button
The settings page: Formbricks address, API key, default workspace and the Test connection button.

Test connection reads the workspaces with the API v2 me endpoint and falls back to the API v1 me endpoint on earlier Formbricks releases, where projects still had environments. Such an environment is remembered, and the add-on then sends both the workspace and environment fields, so older self-hosted instances keep working without any change on your side.

Create a feed

Open a form, go to Settings → Formbricks and click Add New. A feed decides how a submission becomes a Formbricks contact and, if you want, a survey response. A form can have several feeds, for example one per workspace.

Formbricks contact

  • Workspace. Leave the default of the settings, or pick another workspace for this feed.
  • Contact email (required). The merge tag of your email field, for example {Email:2}. Formbricks identifies contacts by email inside a workspace: a contact with this email is updated, otherwise a new contact is created.
  • User ID (optional). The userId attribute that links the contact to the same person in your app, for example a customer number field or {user:ID} for logged-in members. A user ID belongs to one contact only.
  • First name and Last name (optional). Merge tags such as {Name (First):1.3}.
  • Attributes. Map form fields to contact attributes. The key list shows the attributes your workspace already has; you can also type a new key in lowercase letters, digits and underscores, such as company or plan, and Formbricks creates it on first use. Empty answers are skipped, so an empty field never clears what Formbricks already knows.

Survey response

  • Response. Tick it to also record the answers as a response of a survey.
  • Survey. The surveys of the chosen workspace. Choosing a survey reloads the screen with its questions.
  • Answers. Map each survey question, or a hidden field of the survey, to a form field or to custom text with merge tags. Checkbox and multi select fields send every ticked choice as a list, which is what Formbricks stores for multiple choice questions. For choice questions, use choice values in Gravity Forms that match the choice labels in Formbricks.

Finally, Condition lets you send only some entries, for example only when the plan field is Enterprise, or only when the visitor ticked a consent box.

The Formbricks feed settings in Gravity Forms: workspace, contact email, user ID, first and last name, attribute map, survey and the answers map
The feed: workspace, contact email, user ID, names, attribute map, survey and the answers map.

What happens on submit

When the visitor submits the form, Gravity Forms saves the entry first and then runs the feed. The add-on:

  1. reads the attribute keys of the workspace, so existing keys keep their display names;
  2. creates or updates the contact with one call to PUT /api/v2/management/contacts/bulk, matched by email in the workspace;
  3. if the response option is on, records the answers with POST /api/v2/management/responses, linked to the contact through the user ID and marked with the page address of the form;
  4. adds a note to the entry with what was done and saves the response ID on the entry.
A front-end Gravity Form for product feedback with name, email, company, plan, a satisfaction rating, feature checkboxes and an improvement question
A feedback form on the website. The visitor sees only the normal confirmation message.
A Gravity Forms entry screen with the field values and a note confirming the Formbricks contact was saved and the survey response recorded
The entry: the answers, and a note confirming the Formbricks contact and the recorded response.

A failed call never blocks the submission. The visitor always sees your confirmation, the entry is always saved, and the note on the entry explains what went wrong.

Retries never create duplicates

Networks fail, servers restart and people click Resend Feeds twice. The add-on is built so that none of this creates a second contact or a second response:

  • The contact call is an upsert by email: sending the same person again updates the same Formbricks contact.
  • Each response carries a single-use ID made from your site, the entry and the feed. Formbricks keeps that ID unique per survey, so a second attempt for the same entry is refused by Formbricks itself. The add-on then looks up the earlier response and records its ID instead.
  • The response ID is kept on the entry, and Resend Feeds does not post it again.
  • A lock stops two runs of the same feed for the same entry at the same time.

When a call fails for a reason that may pass, such as no answer, a time-out, a rate limit or a server error, the add-on plans an automatic retry after 5 minutes, then 15, then 45. Each retry adds a note. Errors that will not fix themselves, such as a wrong key or an attribute key Formbricks refuses, are not retried; correct the setting and use Resend Feeds on the entry.

Notifications and merge tags

The add-on adds two notification events to forms that have a Formbricks feed: Formbricks: entry sent and Formbricks: sending failed. Use the second to alert your team when an entry could not be sent. Three merge tags work in notifications, confirmations and other add-ons:

  • {formbricks_status}: sent or failed.
  • {formbricks_response_id}: the ID of the recorded response.
  • {formbricks_note}: the text of the last note.

The Formbricks status and response columns can also be added to the entry list and used in entry filters, so you can find every entry that failed.

Errors and troubleshooting

  • HTTP 401: Unauthorized. The API key is wrong or was deleted. Create a new key and save it.
  • HTTP 403: Contacts are not enabled. The Formbricks plan or instance does not include contacts.
  • Invalid attribute key. A new key must use lowercase letters, digits and underscores and start with a letter.
  • The User ID already belongs to another Formbricks contact. Formbricks allows one contact per user ID; check the field you mapped.
  • No workspace is chosen. Run Test connection and pick a workspace in the settings or on the feed.
  • The address redirects. Use the final https address of your Formbricks; the add-on never follows a redirect with your key.
  • Private or local network. Addresses inside your network are refused unless a developer allows the host with a filter.

Privacy and security

The add-on sends only the fields you map, only to the Formbricks address you set, and only over https. The API key is encrypted at rest with AES-256-GCM, removed from any error text, and never written to logs or notes. Private and local addresses are refused, redirects are not followed, and certificates are always verified. Uninstalling the add-on removes its settings, the encrypted key, the saved workspace list and any planned retries; contacts and responses in Formbricks stay where they are.

For developers

  • gffb_contact_attributes filters the attributes before they are sent; gffb_response_answers filters the answers.
  • gffb_contact_saved, gffb_response_recorded and gffb_failed actions run after each step.
  • gffb_auto_retry turns automatic retries off; gffb_timeout changes the request time-out (20 seconds).
  • gffb_allow_private_hosts allows one internal Formbricks host; gffb_allow_insecure_http allows plain http for a test instance.

Frequently asked questions

Does it work with self-hosted Formbricks?

Yes. Enter the address of your instance. Sub-folders, custom ports and older releases that still use environments are supported.

Can one form write to two workspaces?

Yes. Add one feed per workspace and choose the workspace on each feed.

Do I need a survey?

No. Without the response option the add-on only creates or updates the contact, which is enough to target in-app surveys by attribute or segment.

What if Formbricks is down when a form is sent?

The entry is saved, a note explains the error and an automatic retry is planned. Nothing is sent twice when Formbricks comes back.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr