Quick Start

Quick Start

Get your Wealthbox CRM connected to Docusign in five steps:

1. Install the app from the Docusign App Center.
2. Create a Wealthbox API access token — in Wealthbox, go to Settings → API Access and create a personal access token.
3. Connect your account — when adding the connection, review the requested access on the consent screen, click Allow, then paste your Wealthbox API token.
4. Build a workflow in Docusign Maestro and add a Wealthbox step (Read, Writeback, or Note).
5. Run it — contact and opportunity data flows into your envelopes, and signed results flow back into Wealthbox.

Available Actions

• Read from Wealthbox — pull Contact or Opportunity records into your workflow to pre-fill envelope fields.
• Writeback to Wealthbox — create new records or update existing ones with data collected during the agreement flow (form fields, signer data, envelope outcomes).
• Attach as Note — log the completed agreement on the right contact as a linked note carrying the document link.

Key Things to Know

• Records supported: Contacts (read + write), Opportunities (read + write), Notes (create).
• Matching is safest by Record ID. Read a record first, carry its Record ID through the workflow, and use it as the match key in Writeback — this always updates the exact record, never a lookalike.
• Dates are ISO 8601 both ways: birth dates as YYYY-MM-DD, timestamps as 2026-07-09T08:51:00-04:00. Maestro date operators work on them directly.
• After the app updates, reconnect the connection once (Apps → Manage Connections → Reconnect) so Docusign refreshes the cached field catalog.

Implementation Guide & Known Behaviors

Record Matching and Upsert

Writeback steps find the target record using the match conditions you configure, then update the match or create a new record when nothing matches:

• Record ID (recommended) — resolves the exact record. A non-existent or empty Record ID falls through to create, so a read-then-write workflow safely handles both new and existing records.
• First Name + Last Name — matched exactly (case-insensitive). A unique name resolves to its record; if several contacts share the exact name, the step stops with a clear "multiple records" error rather than guessing.
• Email — matches via Wealthbox's email search; no match creates a new contact.
• Opportunities match by Record ID only (or filter by Linked Contact ID). The Wealthbox API cannot search opportunities by name — if a workflow tries, the step fails fast with a message saying so, instead of silently picking a wrong record.

Assigning Users and Linking Contacts by Name

• Assigned To Name (contacts) and Manager Name / Stage Name (opportunities) accept the name and resolve it to the right user or stage automatically. If you map both the ID and the Name, the ID wins. An unknown or ambiguous name stops the step with a clear error — never a silent wrong assignment.
• Linked Contact Name (opportunities) links the opportunity to a contact by exact name — persons and organizations both work. When both Linked Contact ID and Linked Contact Name are mapped, the ID wins.

Data Formatting and Validation

• Amounts accept plain numbers (50000), decimals (1234.56), US-grouped values (1,234.56), and values with a dollar sign ($77,777) — a read amount can be mapped straight back into a write. Ambiguous formats (for example a European decimal comma like 77,50) are rejected with a clear error naming the field, so a misread value can never be written silently.
• Target Close Date accepts ISO 8601 on write and round-trips safely.
• Phone extensions live in the separate Primary Phone Extension field; Primary Phone carries the clean number.

Mandatory Fields in Writeback

Record	Required on create
Contact	First Name, Last Name
Opportunity	Name, Stage, Probability, Amount, Target Close Date
Note	Content, Linked Record ID

If a required field is missing, the step fails with Wealthbox's own validation message (for example "Probability can't be blank"), so the fix is always visible in the workflow run.

Known Behaviors

• Tags replace, not append. Writing Tags replaces the record's full tag set — include every tag the record should keep.
• Company Name creates a link. Writing Company Name links (or creates) an Organization record in Wealthbox.
• Households attach by name. Household Name attaches the contact to an existing household with that name; Household Role sets their role.
• Opportunities can hold several amounts (Fee, Commission, AUM, Other). The app reads and updates the first amount; an update edits it in place and preserves the others, and an amount-only update keeps the existing kind.
• Contact Type and Visible To are read-only. New contacts are created as Person records; visibility is never changed by a writeback.
• The "Overwrite if field value exists" checkbox appears only on required fields — that's a Docusign Maestro platform behavior, not an app setting.

Installation and Configuration

Prerequisites

• A Wealthbox CRM account with permission to create an API access token.
• A Docusign account with access to the App Center and Maestro workflows.

How to Install the App

1. Open the Docusign App Center and find Wealthbox CRM.
2. Click Install and accept the requested permissions.
3. The app appears under Installed Apps in your Docusign admin panel.

Connecting Your Account

1. In Wealthbox, open Settings → API Access and click Create API Access Token. Copy the token.

1. In Docusign, add a connection for the Wealthbox app. A consent screen explains exactly what the app will do with your CRM data (read records, write back agreement data, add notes — secured under ISO 27001). Click Allow to continue, or Deny to cancel.

1. Paste your Wealthbox API token and continue. The app verifies the token against your live Wealthbox account before accepting it — a mistyped token shows an error right there.

1. The connection turns Active and is ready to use in workflows.

Managing Connections

Under Installed Apps → Manage Connections you can rename a connection, disconnect it, or reconnect.

💡 Note: after the app receives an update that changes its field catalog, run Reconnect once — Docusign caches the record and field definitions per connection, and reconnecting refreshes them. If a picker ever shows stale fields or keeps loading, this is the first thing to try.

Adding a New Connection

Multiple connections are supported (for example, different team members' Wealthbox workspaces). Each connection uses its own API token and appears separately in the workflow step configuration.

How to use App

Create a Workflow

To use the integration, create a workflow in Docusign Maestro. The Wealthbox actions appear in the step picker once the app is installed and connected.

Available Wealthbox CRM Actions

• Read from Wealthbox — fetch one record (Contact or Opportunity) and expose its fields as workflow variables.
• Writeback to Wealthbox — create or update a Contact or Opportunity from workflow data.
• Attach as Note — create a Note linked to a contact, typically carrying the completed envelope's document link.

A typical agreement flow: Read the client's contact → pre-fill the envelope → collect signatures → Writeback any updated details → Note the completed agreement on the record.

Read from Wealthbox CRM

Step Overview

The Read step fetches a single record and makes its fields available to later steps (envelope pre-fill, conditions, other integrations).

1. Add the Step to Your Workflow

Add Read from Wealthbox where you need CRM data — usually before the envelope step.

2. Configure Connection and Object

Select your Wealthbox connection, then the record type: Contact or Opportunity.

3. Select Fields

Pick the fields your workflow needs. Available fields:

Contact (read): Record ID, Type, First / Middle / Last Name, Nickname, Prefix, Suffix, Company Name, Job Title, Contact Type, Contact Source, Status, Marital Status, Gender, Birth Date, Client Since, Background Information, External Unique ID, Visible To, Assigned To (ID and Name), Primary Email, Primary Phone (+ Extension), Primary Street Line 1/2, City, State, Zip, Country, Primary Website, Tags, Household (ID, Name, Role, Members), Referred By (ID), Created At, Updated At.

Opportunity (read): Record ID, Name, Description, Target Close Date, Probability, Stage Name, Manager (ID and Name), Next Step, Amount, Amount Kind, Linked Contact (ID, Name, Type), Created At, Updated At.

💡 Note: list-type CRM data is flattened for use in workflows — Tags arrives comma-separated, household members as "Kevin Anderson (Head), Amy Anderson (Spouse)", and the primary email/phone/address are surfaced as the Primary * fields.

4. Identify the Record

Define the condition that selects the record:

• Contacts: Record ID, First + Last Name (exact), Email, Phone, Contact Type, or External Unique ID.
• Opportunities: Record ID, or Linked Contact ID (the opportunity attached to a known contact).

⚠️ Name conditions match exactly — "Kev" won't match "Kevin". If several records match, the step reports it rather than picking one.

Writeback to Wealthbox CRM

Step Overview

The Writeback step creates or updates a record from workflow data — signer-entered form fields, envelope metadata, or values carried from a Read step.

1. Add the Step to Your Workflow

Add Writeback to Wealthbox after the data you want to store exists — typically after signing completes.

2. Configure Connection and Object

Select the connection and the record type: Contact or Opportunity.

3. Map Fields

Map workflow variables onto CRM fields. Writable fields:

Contact (write): First Name*, Last Name*, Middle Name, Nickname, Prefix, Suffix, Company Name, Job Title, Contact Source, Status, Marital Status, Gender, Birth Date, Client Since, External Unique ID, Assigned To (ID or Name), Primary Email, Primary Phone (+ Extension), Primary Street Line 1/2, City, State, Zip, Country, Primary Website, Tags, Household Name, Household Role.

Opportunity (write): Name*, Description, Target Close Date*, Probability*, Stage (ID or Name), Manager (ID or Name), Next Step, Amount, Amount Kind, Linked Contact (ID or Name).

* required on create — see Mandatory Fields.

4. Choose the Match Key

Configure how the step finds the record to update (see Record Matching). With Record ID from an earlier Read step, the update always lands on the exact record; with no match, a new record is created.

💡 Note: every write is idempotent — if Docusign retries a step (a network hiccup, a platform retry), the app recognizes the repeat and will not create duplicate records.

Attach Documents as Notes

Why Notes

Wealthbox's public API does not offer file uploads, so the completed agreement is logged as a Note on the contact carrying the document link — visible in the contact's activity stream, exactly where advisors look.

Configure the Note Step

1. Add the Writeback step and choose the Note record type.
2. Map Content — typically a sentence plus the completed envelope's document link (available as a workflow variable after the signing step).
3. Map Linked Record ID — the contact's Record ID from your Read step.

The note appears in the contact's activity stream immediately, with the link to the signed document.

FAQ & Troubleshooting

Connection Issues

Q: The record picker keeps loading, or shows outdated fields. A: Docusign caches the app's record and field catalog per connection. Go to Installed Apps → Manage Connections → Reconnect, then reopen the picker. This is expected once after any app update.

Q: My API token was rejected when connecting. A: The app verifies the token live against Wealthbox. Re-copy the token from Wealthbox → Settings → API Access (tokens are long — partial copies are the usual cause) and try again. If your Wealthbox admin revoked the token, create a new one.

Matching Issues

Q: Writeback says "Found multiple records" but I only see one matching contact. A: More than one record matched the condition — often an old duplicate or an imported record with the same name. Match by Record ID (read the record earlier in the workflow and carry its ID), or clean up the duplicates in Wealthbox.

Q: My workflow matches an Opportunity by name and fails. A: That's by design — the Wealthbox API cannot search opportunities by name, so the app refuses rather than risk updating the wrong deal. Match opportunities by Record ID, or filter by Linked Contact ID.

Q: I left Record ID empty on an update and it created a new record. A: An empty or unmatched Record ID means "no existing record" and falls through to create. That's the upsert pattern working — carry a real Record ID to force an update.

Writeback Issues

Q: The Amount I wrote shows as a different number, or the step failed on the amount. A: The app accepts 50000, 1234.56, 1,234.56, and $77,777 — including values read straight from another opportunity. Ambiguous formats (like a European decimal comma, 77,50) are rejected with an error naming the field so nothing incorrect is stored silently.

Q: Background Information reads back empty even though the value is visible in Wealthbox. A: Fixed in the July 20, 2026 update. Wealthbox's API returns this field under a different name than it accepts on writes, and earlier app versions read the wrong one. Writes were unaffected. No reconnect or workflow change is needed.

Q: My tags disappeared after a writeback. A: Writing Tags replaces the record's whole tag set. Include the full list of tags the record should have — for example, read the current tags first and append the new one.

Q: The step failed with a message like "Probability can't be blank". A: That message comes directly from Wealthbox's validation — an opportunity create needs Name, Stage, Probability, Amount, and Target Close Date. Map all required fields (marked * above).

Document Attachment

Q: Can I upload the signed PDF file into Wealthbox? A: Wealthbox's public API has no file-upload endpoint, so no integration can push binary files into it. The supported pattern is the linked Note carrying the completed document's link — it lands in the contact's activity stream where the team already works.

Performance

Q: Workflow steps with Wealthbox seem slower than other steps. A: The Wealthbox API allows roughly one request per second per account. Single reads and writes are quick; workflows that fan out many CRM operations at once are paced to respect that limit.