Gravity Forms CiviCRM Add-On Setup Guide

The Gravity Forms CiviCRM Add-On sends your Gravity Forms entries to CiviCRM. Each feed can create or update a contact (Individual, Organization or Household), match people who are already in CiviCRM, add their e-mail address, phone number and address, fill your CiviCRM custom fields, add the contact to groups and tags, record an activity with the form answers, record a contribution, and register the contact for a CiviCRM event. It works with CiviCRM installed on the same WordPress site, and with CiviCRM on another website through the CiviCRM API version 4. This guide covers the connection, the feed settings, payments, what you see on each entry, and the most common questions.

What you need

• Gravity Forms 2.8 or newer (tested with 2.8, 2.9 and 3.1), WordPress 6.5 or newer and PHP 7.4 or newer.
• CiviCRM with API version 4 (any current CiviCRM release; the add-on was tested with CiviCRM 6.20 for WordPress on MariaDB).
• For another CiviCRM site: a CiviCRM user with an API key (or a JSON Web Token) and the authenticate with api key permission.

Install and activate

• Upload the add-on zip in Plugins → Add New → Upload Plugin and activate it.
• Go to Forms → Settings → CiviCRM, enter your GravityExtra licence key and press Activate License.
• The CiviCRM connection settings appear once the licence is active. Without an active licence nothing is sent to CiviCRM.

Step 1: connect CiviCRM

Under Where is CiviCRM? choose one of two modes.

On this WordPress site. Choose this when the CiviCRM plugin runs on the same WordPress site as your forms. The add-on calls CiviCRM directly on the server: no API key, no web request, nothing to set up. The settings screen shows CiviCRM is active on this WordPress site when CiviCRM is found. Feeds write what you set up in the feed, whoever submits the form, so visitors do not need CiviCRM permissions.

Another CiviCRM site (API). Choose this when CiviCRM runs on a different website (WordPress, Drupal, Backdrop, Joomla or CiviCRM Standalone). Fill in:

• CiviCRM site address: the address of that website, starting with https://, for example https://crm.yourcharity.org.
• API address style: Clean URLs for Drupal, Backdrop, Standalone and WordPress sites with CiviCRM clean URLs; WordPress for other WordPress sites (/?civiwp=CiviCRM&q=civicrm/ajax/api4/…); Joomla; or Custom with your own address template that contains {entity} and {action}.
• API key or JWT: the API key of the CiviCRM contact the add-on works as. A dedicated API user is best. It is sent in the X-Civi-Auth header and stored encrypted; it is never shown again or written to notes and logs.
• Site key (if required): the CiviCRM site key, if your CiviCRM authentication settings ask for it. Sent in the X-Civi-Key header and stored encrypted.
• Timeout: how long to wait for an answer (20 seconds by default).

Save the settings and press Test connection. The add-on reads one contact id and the lists the feeds use, and writes nothing. Reload CiviCRM lists reads the groups, tags, types and custom fields again after you change them in CiviCRM (they are kept for 10 minutes).

Preparing the API user on the CiviCRM site

• Create or pick a CiviCRM contact with a CMS user account and give that user role the authenticate with api key permission, plus permissions to view and edit contacts, groups, tags, activities, contributions and events (only the parts your feeds use).
• Give the contact an API key (in CiviCRM on the contact’s API Key tab, or by your system administrator).
• In CiviCRM’s authentication settings, allow API keys for the X-Civi-Auth header (new CiviCRM sites accept only tokens there until you add API keys).

The API key, token and site key can also be set in wp-config.php with GECIVI_API_KEY and GECIVI_SITE_KEY; they are then not stored in the database at all.

Step 2: create a feed and map the contact

Open your form, go to Settings → CiviCRM and press Add New. Give the feed a name and pick the Contact type: Individual, Organization or Household. The field map changes with the type.

• Individual: first, middle and last name, job title, birth date.
• Organization: organization name, legal name, SIC code.
• Household: household name.
• All types: e-mail, phone, street address, address line 2, city, state or province (name or code), postal code, country (name or two-letter code), nickname and external ID. A Gravity Forms Address field can be mapped part by part.

Choose the location type for the e-mail, phone and address (Home, Work and so on) and the phone type. Under CiviCRM custom fields add a row for each custom field you want to fill. The list shows the custom fields of the chosen contact type, read from your CiviCRM. For custom fields with options, use the CiviCRM option values as the choice values of your Gravity Forms field; multiple-choice custom fields take a checkbox or multi-select field. Yes/No fields accept Yes, No, 1 or 0; date fields accept the usual date formats.

A contact needs a name or a valid e-mail address. If an entry has neither, nothing is sent and the entry gets a note.

Step 3: matching people who are already in CiviCRM

Find an existing contact by decides when a form submission updates an existing contact instead of creating a new one:

• Same e-mail address (default): a contact of the same type with that e-mail address, primary addresses first.
• CiviCRM unsupervised rule: the duplicate rule your CiviCRM uses for this contact type. Any other CiviCRM dedupe rule of the type is listed too.
• Always create a new contact.

When the contact exists: Fill empty fields only (default) leaves what is already in CiviCRM alone; Update with the new values writes every mapped value that is not empty; Do not change the contact. New e-mail addresses and phone numbers are always added to the contact, never twice. Empty form values never clear CiviCRM data. Contact source is saved on new contacts and supports merge tags.

Step 4: groups, tags and an activity

Tick the CiviCRM groups to add the contact to (for example your newsletter list) and the tags to add. Smart groups are not listed, because CiviCRM fills those itself.

Tick Record an activity to keep a record of the submission on the contact: choose the activity type, the subject and the details (merge tags work; {all_fields} by default), and the status Completed or Scheduled for a follow-up. The activity date is the entry date. One activity is recorded per entry and feed, also when you resend the entry.

Step 5: contributions and payments

Tick Record a contribution to record a donation or payment on the contact. Choose where the amount comes from (the form total or any number, product or total field), the financial type and, if you like, the payment method.

The contribution status follows the Gravity Forms payment status:

• Completed only when the payment status is Paid, with the transaction id of the payment.
• Pending while the payment is processing, pending or authorized. When the payment add-on later reports the payment as complete, the contribution moves to Completed; a refund moves it to Refunded, a failed payment to Failed, a voided authorization to Cancelled. A refunded, failed or cancelled contribution never goes back to Completed.
• Entries without a payment (cheques, pledges, pay later) are recorded as Pending, or not at all if you choose Do not record a contribution.

This works with the Gravity Forms payment add-ons and the GravityExtra payment gateways that report payments to Gravity Forms. To send the whole feed only after the payment is received, open your payment feed and tick Send to CiviCRM only when the payment is received. Each contribution gets a unique invoice id, so a retry or a resend never records it twice.

Step 6: event registrations

Tick Register the contact for a CiviCRM event, pick the event, the participant role (for example Volunteer) and the status (Registered by default). A contact is registered once per event: a second sign-up updates the same registration.

Conditional logic and several feeds

Turn on Conditional logic to send an entry only when the answers match, for example only volunteers for the morning shift, or only donations above a certain amount. A form can have several feeds: one that adds every visitor to the newsletter group and another that records the donation and the event registration.

What you see on each entry

Every entry that was sent gets a note with the CiviCRM contact id, a link to the contact in CiviCRM and a line for each step (contact, e-mail, phone, address, groups, tags, activity, contribution, event). The entry screen has a CiviCRM box with the status and the ids. The entry list can show the CiviCRM contact ID and CiviCRM status columns, and the {civicrm_contact_id} merge tag puts the contact id in confirmations and notifications, for example as a supporter number.

Errors and retries

• If CiviCRM cannot be reached or has a server error, the add-on tries again after 5 minutes, 30 minutes and 2 hours (you can turn this off under Errors and retries).
• Errors in the data, such as a field CiviCRM refuses or a wrong API key, are not retried: the note says what went wrong. Fix the feed or the settings and press Resend in the entry’s Process feeds box.
• If one step fails (for example the contribution), the other steps still run and the entry shows Sent with errors.
• Resending an entry is safe: the same contact is used, and no second activity, contribution, group membership, tag or event registration is created.

Privacy and security

The add-on only talks to your CiviCRM (and to GravityExtra for licence checks and updates). API keys and site keys are stored encrypted with your site’s own WordPress keys, or set in wp-config.php, and are never written to notes or logs. Remote addresses must use https://. The settings and the Test connection button need the Gravity Forms settings permission. Uninstalling the add-on removes its settings and licence data; it never deletes anything in CiviCRM.

Frequently asked questions

Does it work with CiviCRM on Drupal, Backdrop or Joomla? Yes, through the API mode with the Clean URLs, Joomla or Custom address style. Your forms stay on WordPress.

Do I need an API key when CiviCRM is on the same site? No. The add-on calls CiviCRM directly on the server.

Test connection says the site did not answer with API data. The address style probably does not match your site (for example Clean URLs on a WordPress site without CiviCRM clean URLs). Try the WordPress style. A security plugin or a login page in front of CiviCRM can also block the API.

Test connection says HTTP 401 or 403. CiviCRM refused the credentials: check the API key, that the user has the authenticate with api key permission, that API keys are allowed for the X-Civi-Auth header, and the site key if your CiviCRM requires one.

Can it renew memberships? Not in version 1.0.0. Memberships are planned for a later version. You can record the membership payment as a contribution with the Member Dues financial type today.

CiviCRM is a registered trademark of CIVICRM LLC. This add-on is made by GravityExtra and is not affiliated with or endorsed by CIVICRM LLC.