Mappings for Wealthbox documentation

Introduction

Mappings for Wealthbox sends every Gravity Forms submission straight into Wealthbox CRM as a contact, with no Zapier, no CSV exports and no copy and paste. You pick a form, choose which Wealthbox field each form field goes to, and publish. From then on, each submission creates the contact in Wealthbox within seconds.

It is built for financial advisors, RIAs and the agencies that run their websites: firms that capture leads on WordPress and live in Wealthbox. The plugin comes in two parts:

• Mappings for Wealthbox (free) creates new contacts from any Gravity Form using the standard Wealthbox contact fields.
• Mappings for Wealthbox Pro ($49, one time, one site) is an add-on that installs next to the free plugin. It adds custom fields, updating existing contacts, sync logs and GP Nested Forms support.

See the Free vs Pro comparison for the full list.

Requirements and installation

Install the free plugin

1. In WordPress go to Plugins › Add New › Upload Plugin.
2. Upload mappings-for-wealthbox.zip and click Install Now.
3. Click Activate. A new Wealthbox menu appears in the admin sidebar.

Install Pro

1. Make sure the free plugin is installed and active. Pro is an add-on and will not run without it.
2. Upload mappings-for-wealthbox-pro.zip the same way and activate it.
3. Pro creates two database tables on activation, for the contact index and the sync logs. A Logs item appears under the Wealthbox menu.

If the free plugin is missing, Pro shows a notice asking you to install and activate it, and does nothing else.

Connecting to Wealthbox

The plugin talks to Wealthbox with one access token, saved under Wealthbox › Settings. The page has two tabs: General and Connection & Cache.

Get your access token

1. Log in to Wealthbox and open Settings › API Access.
2. Create a token and copy it.

General tab

Paste the token, check the base URL and click Save Changes.

Connection & Cache tab

• Test connection sends one request to Wealthbox. You see a success message when it works, "Authentication failed (HTTP 401 or 403)" for a bad token, or the HTTP error for anything else. Save the token before you test.
• Custom field cache (Pro) shows how many custom fields are cached. It refreshes on its own every 3 hours. Click Clear cache & re-fetch fields after adding or renaming a custom field in Wealthbox.

Requests time out after 20 seconds.

Creating a mapping

A mapping links one Gravity Form to Wealthbox. It is saved under Wealthbox › Mappings and only runs once it is published.

1. Go to Wealthbox › Mappings › Add New.
2. Give it a title you will recognise, for example "Contact page form".
3. Choose the form under Gravity Form. The field table loads straight away.
4. (Pro) Choose the Action and, for update modes, the Match using field.
5. For each row, pick the Wealthbox field in the right column. Leave a row on Not mapped to skip it. The dropdowns are searchable.
6. Click Publish.

The field table

• The left column lists every form field with its Gravity Forms key, for example 1.3.
• Fields with several inputs (Name, Address) appear once as the whole value, then once per sub input such as "Name, First" or "Address, City".
• Checkbox and Multi Select fields appear once. All selected choices are sent together.
• Page breaks, sections, HTML blocks and CAPTCHA are left out.
• Nested Forms child fields carry a nested tag (Pro).

Hidden fields

Hidden Gravity Forms fields such as user ID, UTM tags or tracking values are hidden from the table by default. Tick Show hidden fields to map them.

Duplicate a mapping

Hover a mapping in the list and click Duplicate. You get a draft copy with the same form, action, match settings and field map.

One mapping per form

If more than one published mapping points to the same form, only the most recently published one runs. Keep the others as drafts. The Mappings list has a sortable Gravity Form column so you can see which form each mapping uses.

Wealthbox fields and value formatting

The free plugin maps to nine standard Wealthbox contact fields. Pro adds every custom field you have in Wealthbox.

If no first or last name is mapped or filled in, the contact is saved as Web Lead, because Wealthbox needs a name.

How Gravity Forms values are sent

If you map a single sub input (for example only the consent checkbox 5.1), the raw value of that input is sent instead.

Pro: sync actions and contact matching

Pro lets each mapping decide what happens when someone already in Wealthbox submits the form again. Pick it under Action on the mapping screen.

The free plugin always uses Create contact only. If you deactivate Pro, mappings set to an update action are skipped, not turned into creates, until Pro is active again.

Match using

• The form field that holds the value, for example your Email field.
• The type, Email or Phone. Emails are trimmed and lowercased. Phone numbers keep only their digits, so "(555) 010-2233" and "5550102233" match.

How the match works

Each time the plugin creates or updates a contact, it saves a SHA-256 fingerprint of that contact's email and phone, with the Wealthbox contact ID, in its own index table. The real email and phone are never stored there. On the next submission it fingerprints the match value and looks it up: one database lookup, no API call.

The index only knows contacts the plugin itself created or updated. A contact already in Wealthbox before you installed Pro is not found yet, so Create and update makes a second record for that person. Matching existing Wealthbox contacts is planned for an update.

Pro: custom fields

With Pro active, every Wealthbox contact custom field appears in the mapping dropdown under Custom fields, below the native fields.

Auto matching

When you load a form, Pro pre-selects a custom field for any form field whose label matches the custom field's name, ignoring capitals and extra spaces. "Annual Income" in Gravity Forms matches "annual income" in Wealthbox. Check the suggestions before you publish. A saved choice always wins.

Name, email and phone in custom fields

If you map a Gravity Forms Email, Phone or Name field to a custom field, Pro also fills the matching native field, so the contact always gets a real name, email and phone:

• Email field: also added as the contact's email address
• Phone field: also added as the contact's phone number
• Name, First (x.3): also set as first name
• Name, Last (x.6): also set as last name

The cache

Custom field definitions are fetched 100 at a time for each document type you selected in Settings, up to 5,000 fields, and cached for 3 hours so the mapping screen never waits on the API. An empty cache refills itself on the next page load. Only Contact custom fields appear in the mapping dropdown today.

Pro: GP Nested Forms

Pro lets you map the fields inside a Gravity Perks Nested Forms field, for example several addresses, dependents or accounts entered on one form. Each child field appears as its own row, labelled "Parent field → Child field", with a key like nested:12:3 (parent field 12, child field 3).

At submission, every child entry becomes one numbered line, labelled with the child field's name:

Address-1: 12 High St, Porto, 4000-123, Portugal
Address-2: 8 Rua Nova, Gaia, 4400-001, Portugal

• Map the whole child field to get all its parts joined with commas, as above.
• Map one sub input (nested:12:3.3) to get only that part per line.
• Send nested rows to a text custom field or to Background information, because the result is several lines long.
• Nested rows cannot be the Match using field.

Pro: sync logs

Every submission on a mapped form writes one row to Wealthbox › Logs, so you can see exactly what was sent and what Wealthbox answered.

Sort by time, form, entry, status or HTTP code, filter by a From and To date, and set rows per page under Screen Options. Logs hold submitted form data, so treat them as personal data. They are kept until you uninstall Pro; automatic clean up is planned for an update.

Developer reference

The free plugin is a small engine with hooks. Pro is built entirely on those same hooks, so you can extend it the same way.

Free plugin hooks

Pro hooks

Example: tag every web lead

add_filter( 'wbm_contact_payload', function ( $payload, $entry, $form ) {
    $payload['tags'] = [ 'Website lead' ];
    return $payload;
}, 10, 3 );

Where data is stored

The code uses the MappingsForWealthbox namespace (Pro: MappingsForWealthbox\Pro). The Wealthbox_Resource interface means support for more Wealthbox record types can be added as new classes, without changing the sync engine.

Deactivating and uninstalling

Deactivating never deletes anything. Deleting a plugin removes only that plugin's own data, and nothing in Wealthbox is ever deleted.

Troubleshooting and FAQ

Known limitations

• Update modes only find contacts the plugin created or updated itself.
• Logs are not cleaned up automatically.
• Only one published mapping per form is used.
• Only Wealthbox Contacts are supported today.

Questions the docs do not answer? Contact me.

Changelog and credits

Built by Samama Tahir. Licensed under GPL v2 or later. Wealthbox is a trademark of its owner and Gravity Forms is a trademark of Rocketgenius. This plugin is independent and not affiliated with either.