Mappings for Wealthbox Documentation

Introduction

Mappings for Wealthbox sends every Gravity Forms submission into Wealthbox CRM as a contact. You don't need Zapier, CSV exports or copy and paste. You pick a form, choose the Wealthbox field for each form field, and publish. From then on, each submission creates a 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 work 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 installed alongside the free plugin. It adds custom fields, updates to 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. Download the free plugin.
2. In WordPress, go to Plugins › Add New › Upload Plugin.
3. Upload mappings-for-wealthbox.zip and click Install Now.
4. 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 doesn't run without it.
2. Upload mappings-for-wealthbox-pro.zip (you get it after buying Pro) the same way, and activate it.
3. On activation, Pro creates two database tables: one for the contact index and one for 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 connects 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 automatically every 3 hours. Click Clear cache & re-fetch fields after you add or rename a custom field in Wealthbox.

Requests time out after 20 seconds.

Creating a mapping

A mapping links one Gravity Form to Wealthbox. Mappings are saved under Wealthbox › Mappings and only run once published.

1. Go to Wealthbox › Mappings › Add New.
2. Give it a title you'll recognize, for example “Contact page form”.
3. Choose the form under Gravity Form. The field table loads immediately.
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 fields 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 over 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 in your Wealthbox account.

If no first or last name is mapped or filled in, the contact is saved as Web Lead, because Wealthbox requires 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

With Pro, each mapping decides what happens when someone already in Wealthbox submits the form again. Choose 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 query, no API call.

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

Pro Custom fields

With Pro active, every Wealthbox contact custom field appears in the mapping dropdown under Custom fields, below the standard 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 choice you've saved always takes priority.

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 standard 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 the first name
• Name, Last (x.6): also set as the last name

The cache

Custom field definitions are fetched 100 at a time for each document type 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 can 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).

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

Address-1: 120 Main St, Austin, TX 78701, United States
Address-2: 45 Oak Ave, Denver, CO 80203, United States

• 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 on each line.
• Send nested rows to a text custom field or to Background information, because the result spans several lines.
• Nested rows can't be used as 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 how Wealthbox responded.

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 contain submitted form data, so treat them as personal data. They are kept until you uninstall Pro; automatic cleanup is planned for a future update.

Developer reference

The free plugin is a small engine with hooks. Pro is built entirely on those same hooks, so you can extend the plugin 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). Because of the Wealthbox_Resource interface, 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

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.

Have a question the docs don't answer? Contact us.

Changelog

Built by Metafoid. 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.