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

Gravity Forms Virtuous Integration Setup Guide

Updated 8 min read Gravity Forms CRM & Email Marketing
On this page
  1. Step 1: Install and License the Add-on
  2. Step 2: Connect Virtuous CRM+
  3. Create the API key in Virtuous
  4. Save and test the connection
  5. Step 3: Create a Virtuous Feed
  6. Contact type and contact details
  7. Email type, phone type and address
  8. Tags, lists and custom fields
  9. Matching and conditions
  10. Field Mapping Reference
  11. Privacy and Consent
  12. Conditional Logic
  13. Developer Filter: gravityextra_virtuous_contact_transaction
  14. Checking Delivery on the Entry Screen
  15. Troubleshooting & FAQ
  16. The note says the Virtuous rate limit was reached.
  17. The entry says Sent, but I cannot find the contact in Virtuous.
  18. The connection fails or notes mention the API key or permission group.
  19. The note says a name, email, phone or street address is required.
  20. Resource Hub

Supporters who sign up on your website should not wait in an inbox until someone retypes them into your CRM. The Gravity Forms Virtuous Premium Add-on sends each submission to Virtuous CRM+ with the supporter’s name, email, phone, mailing address, tags, origin segment, email lists and custom fields, using the import path Virtuous recommends, so matching and duplicate checks are handled by Virtuous itself.

This guide covers creating the API key, building a feed, how Virtuous processes the import, and what to do when a submission is not delivered.

System Requirements & Prerequisites

  • WordPress: Version 6.5 or higher
  • PHP: Version 7.4 or higher
  • Gravity Forms: Version 2.5 or higher
  • Virtuous CRM+: A Virtuous administrator who can create an API key with a permission group that can create contacts
  • GravityExtra license: The Virtuous add-on installed, activated and licensed with an active GravityExtra license key

Step 1: Install and License the Add-on

  1. Go to Plugins → Add New → Upload Plugin, upload the add-on ZIP file and click Activate.
  2. Open Forms → Settings → Virtuous.
  3. Enter your license key in the Gravity Extra License section and save. The Virtuous CRM+ API settings appear once the license is active.

Step 2: Connect Virtuous CRM+

Create the API key in Virtuous

A Virtuous administrator creates the key under Settings → All Settings → Connectivity → API Keys and picks a permission group that can create contacts.

Save and test the connection

  • API Key (required): paste it and click Save Settings. It is stored in a masked password field and never appears in entry notes, logs or backup emails.
  • Connection: the add-on reads your organization and shows “Connected to Virtuous — [organization name].” The result is remembered for up to an hour; Test connection checks again immediately and also refreshes the custom field list used in feeds.
  • Backup email for failed submissions: defaults to the site admin email. If Virtuous cannot be reached or rejects a submission, the contact details are emailed here. Leave it empty to turn it off.
Virtuous CRM+ API settings in Gravity Forms connected to the organization, with the Test connection button and backup email
Forms → Settings → Virtuous connected to the Hope Foundation organization.

Contacts appear after Virtuous processes the import

Each submission is sent as a Contact Transaction. Virtuous accepts it right away, then matches it to an existing contact or creates a new one when it processes the import (Virtuous documents this as a nightly batch). Until then the contact is not visible in Virtuous; pending items are listed under Imports in Virtuous.

Step 3: Create a Virtuous Feed

Open your form, go to Settings → Virtuous and click Add New. The button is available once the API key is saved.

Contact type and contact details

Choose the Contact Type: Household (default), Organization or Foundation. It must match a contact type configured in Virtuous. If visitors choose for themselves, select that field in Contact Type from field; its choice values must be Household, Organization or Foundation. Map First Name and Last Name, or a single Full Name field (split at the last space), plus the optional title, middle name and suffix. Organization and Foundation contacts use Organization Name.

Virtuous feed contact section with feed name, contact type, name, email and phone mapping
Contact mapping for a Stay in Touch form.

Every submission needs a name (Household) or an organization or name (other types), and at least an email, a phone or a street address so Virtuous can match the contact. Entries without them are not sent and get a note explaining what is missing.

Email type, phone type and address

Email Type (default “Home Email”) and Phone Type (default “Mobile Phone”) must match contact method types in Virtuous, such as “Work Email” or “Home Phone”. Map the parts of an Address field; country names are sent as two-letter codes (US), the state is sent as entered.

Virtuous feed email type, phone type and mailing address mapping
Email and phone types with the Mailing Address mapping.

Tags, lists and custom fields

  • Tags: comma-separated tag names, merge tags allowed. Tags must already exist in Virtuous, because they cannot be created through the API. Tags from field adds the selected choices of a field, for example a checkbox whose values are Virtuous tag names.
  • Origin Segment Code: the code of the Virtuous segment (campaign or appeal) the contact came from, for example WEBFORM.
  • Email Lists: comma-separated Virtuous email list names. With an Email List Consent Field selected, lists are only sent when the visitor ticked it.
  • Custom Fields: the dropdown lists your Virtuous contact custom fields, or you can type a field name exactly.
  • Message / Notes Field: Contact Transactions have no notes field, so the message is saved in a text custom field you name in Custom Field for the Message, for example “Web Form Message”.
Virtuous feed tags, tags from field, origin segment code, email list with consent field, custom fields and message field
Tags, interest checkboxes as tags, segment code, newsletter list with consent, a custom field and the message field.

Tags and custom fields have a safe fallback. If Virtuous rejects the submission with a validation error while it contains tags or custom fields, it is sent once more without them, so the contact is not lost. The entry gets a warning note with the Virtuous error; check that the tag names exist in Virtuous and the custom field names are exact.

Matching and conditions

Reference Source (default GravityExtra – {form_title}) is shown in Virtuous as the source of the import. Together with the entry reference (your site address + entry ID, for example hopefoundation.org:entry:1042) it lets Virtuous recognise resubmissions. The reference is saved with the entry the first time it is sent, so renaming the form later does not change it.

Virtuous feed Reference Source setting and conditional logic
Reference Source and the conditional logic switch.

Field Mapping Reference

Feed setting Virtuous field How it is sent
Contact Type / Contact Type from field contactType Field value wins when filled; Household by default
Title, First, Middle, Last Name, Suffix title, firstName, middleName, lastName, suffix Full Name is split at the last space
Organization Name name For Organization and Foundation contacts
Email + Email Type, Phone + Phone Type email, emailType, phone, phoneType As entered
Address address1, address2, city, state, postal, country Country converted to a two-letter code
Tags + Tags from field tags One comma-separated list, duplicates removed
Origin Segment Code originSegmentCode Text or merge tags
Email Lists emailLists Only with consent when a consent field is set
Custom Fields + Message customFields Custom field name and value
Reference Source + entry reference referenceSource, referenceId Saved on first send and reused
  • Email list consent: email lists are optional. Select your newsletter checkbox in Email List Consent Field so supporters are only added to lists they agreed to. Leave the box unticked by default.
  • Credentials: the API key is sent only in the request header and is removed from every note, log message and backup email.
  • Backup email contents: the backup email lists the contact fields, tags, lists and custom fields, the error and a link to the entry. Send it to an inbox your team controls.

Conditional Logic

Tick Enable Condition to send only matching entries. Examples: send only when “Email Updates” is ticked, send only when “I’m Interested In” includes Volunteering, or create one feed per contact type with a different origin segment code.

Developer Filter: gravityextra_virtuous_contact_transaction

The gravityextra_virtuous_contact_transaction filter lets developers change the Contact Transaction before it is sent. It passes $body (the Virtuous fields listed above), $feed, $entry and $form, and must return the body. This example sets the origin segment for sign-ups from a gala page:

functions.php
PHP
// Credit sign-ups from the spring gala page to the GALA2026 segment
add_filter( 'gravityextra_virtuous_contact_transaction', function( $body, $feed, $entry, $form ) {
    if ( false !== strpos( (string) rgar( $entry, 'source_url' ), '/spring-gala/' ) ) {
        $body['originSegmentCode'] = 'GALA2026';
    }
    return $body;
}, 10, 4 );

The gravityextra_virtuous_tags and gravityextra_virtuous_custom_fields filters change how tags and custom fields are formatted.

Checking Delivery on the Entry Screen

Entries from a form with an active Virtuous feed show a Virtuous box with the status and the Reference ID. Because Virtuous returns no contact ID at this stage, the status reads Sent to Virtuous (appears after Virtuous processes the import), and the entry note records the reference source and ID.

Virtuous status box showing Sent to Virtuous, the stable reference ID and the Send to Virtuous again button
A delivered entry with its stable reference ID.

When the status is Not delivered, the note gives the reason and the backup email is sent. Fix the cause and click Send to Virtuous again.

Virtuous status box showing Not delivered, the entry reference ID and the Send to Virtuous again button
An entry that was not delivered because of the rate limit.
Gravity Forms entry notes showing the Virtuous rate limit message and the successful resend with the same reference
Entry notes for the rate limit and the successful resend with the same reference.

Resending is safe. Send to Virtuous again uses the same reference, so Virtuous updates the same contact instead of creating a duplicate. It reruns every active Virtuous feed on the form whose conditions match, and is available to users who can edit entries.

Troubleshooting & FAQ

The note says the Virtuous rate limit was reached.

Virtuous allows 1,500 API requests per hour for your whole organization, shared by every integration. After a rate-limit response the add-on pauses sending until the limit resets (10 minutes when Virtuous gives no time). Submissions during the pause are marked Not delivered with the time sending resumes, and the backup email is sent; resend them afterwards.

The entry says Sent, but I cannot find the contact in Virtuous.

This is expected until Virtuous processes the import. Pending items are listed under Imports in Virtuous; the entry note shows the reference source and ID that were sent.

The connection fails or notes mention the API key or permission group.

A rejected key needs a new key from Settings → All Settings → Connectivity → API Keys. A permission error means the key’s permission group cannot create contacts; a Virtuous administrator can change it there. Save, click Test connection and resend the affected entries.

The note says a name, email, phone or street address is required.

Map the missing fields in the feed and make them required on the form, then resend the entry. A note about the GravityExtra license means sending is paused until the license is active again; Forms → Settings → Logging gives a detailed trace.

Resource Hub

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