Record ID as the match key is the most reliable way to hit the exact record and avoid mismatches.Writeback steps find the target record using the match condition you configure. The behavior depends on the Write setting you pick in the Writeback step: Update, Create, or Update or Create.
Match identifiers:
| Record | Required on create |
|---|---|
| Contact | First Name, Last Name |
| Opportunity | Name, Stage Name, Probability, Amount, Target Close Date |
Assigned To Name (contacts and opportunities; the same "Assigned" field you see on the Wealthbox edit page). It resolves to a workspace user (the person the record is assigned to), not a contact from the Contacts list. Assigned To ID is also available; if you map both, the ID wins.Stage Name (opportunities) accepts the stage name as Wealthbox shows it on the opportunities page.Linked Contact Name (opportunities) links the opportunity to a contact by exact name. When both Linked Contact ID and Linked Contact Name are mapped, the ID wins.50000), decimals (1234.56), US-grouped values (1,234.56), and values with a dollar sign ($77,777), so a read amount can be mapped back into a write. Ambiguous formats (for example a European decimal comma like 77,50) are rejected with an error naming the field, so a misread value is not written.Birth Date, Client Since and Target Close Date are true date fields, so Docusign gives you a date picker and date operators instead of free text. They accept a full ISO 8601 value or a plain YYYY-MM-DD.Primary Phone Extension field; Primary Phone carries the clean number.These fields accept a fixed set of values. Values are case-sensitive, and an invalid value stops the step.
| Field | Accepted values |
|---|---|
| Contact Type | Client, Past Client, Prospect, Vendor, Organization |
| Contact Source | Referral, Conference, Direct Mail, Cold Call, Other |
| Status (Active/Inactive) | Active, Inactive |
| Marital Status | Married, Single, Divorced, Widowed, Life Partner, Separated, Unknown |
| Gender | Female, Male, Non-binary, Unknown |
| Household Role | Head, Spouse, Partner, Child, Grandchild, Parent, Grandparent, Sibling, Other Dependent |
Contact Type and Contact Source are customizable per Wealthbox account. The values above are the standard set, and an account may have additional options configured.
A couple of conventions for the free-text contact fields:
California) or an abbreviation (CA).Date and phone-extension formatting is covered under Data Formatting and Validation, and Tags behavior under Known Behaviors.
| Field | Accepted values |
|---|---|
| Amount Kind | Fee, Commission, AUM, Other |
| Probability % | A whole number from 0 to 100, in 10-point steps (0, 10, 20 … 100) |
| Stage Name | The stage names configured in your Wealthbox pipeline (account-specific). The default pipeline is Evaluation, Identify Decision Makers, Qualification, Needs Analysis, Review, Proposal. The name is resolved to the stage. |
The app can write a Note to Wealthbox as part of a workflow.
Notes are create-only: the step creates a note; there is no update or delete.
| Field | Required | Notes |
|---|---|---|
| Content | Yes | The note body: text and/or a link to the signed document. |
| Linked Record ID | No | Record ID of the record the note attaches to. |
| Linked Record Type | No | Contact, Opportunity, or Project. |
| Visible To | No | Everyone, Private, or a user group id. |
Where the note appears depends on whether it is linked:
So if the note should appear on a specific contact, always map Linked Record ID, and it must be a real record id (a placeholder such as <contact record id> stops the step with a 400).
Tags replaces the record's full tag set, so include every tag the record should keep.Household Name attaches the contact to an existing household with that name; Household Role sets their role.Linked Record ID is created but not attached to any record. It appears in the Home activity feed instead of on a client record.This section walks through installing the Wealthbox app and connecting it to your Wealthbox CRM account for use with Docusign Workflow Manager.
Open the Docusign App Center and search for Wealthbox in the search bar.
Click the Wealthbox app card to open its detail page, then click Install App.
Review the access the app requests and click Install and Authorize.
The app now appears with an Installed status.
Once installed, authorize the connection between Docusign and your Wealthbox account.
On the installed app page, click Connect Account.
Connection Visibility: choose how the connection is shared:
Name Connection: enter a clear name (e.g., "Wealthbox-Connection-1"); it appears in workflow steps, so make it easy to identify. Click Log In.
On the Wealthbox consent screen, review the requested access and click Allow to continue (or Deny to cancel).
The app then asks for your Wealthbox API access token (see Getting Your Wealthbox API Token below).
You need a Wealthbox API access token to finish connecting. In Wealthbox (open it in another tab):
Open the ⋮ menu in the top-right corner and choose Workspace Settings.
Under Personal, open API Access and click Create Access Token. Copy the generated token.
⚠️ Two things about the token: it cannot be viewed again after it is created, so copy it somewhere safe. You will need it again if you ever Reconnect the connection; otherwise you will have to create a new one. The token-entry step in Docusign is also time-limited, so have the token ready before you start: spending more than a few minutes on it can make Docusign show a Failed message.
Back in Docusign, paste the token and click Continue to Docusign. Once it verifies, the window closes and the connection is added.
The connection turns Active and is ready to use in your workflow steps.
You can add, rename, reconnect, or delete connections at any time without reinstalling the app. On the Wealthbox app page, open the Manage dropdown.
Select Manage Connections to see every connection with its type, status, last-updated time, and who created it. Use the three-dot (⋮) menu next to a connection:
Multiple connections are supported (for example, different team members' Wealthbox workspaces). Use Manage → New Connection on the app page, or + Add New Connection on the Connections page, and follow the same steps as above. Each connection uses its own API token and appears separately in workflow steps.
The Wealthbox app lets you work with your Wealthbox CRM data directly inside Docusign Workflow Manager: build workflows that read Wealthbox records, pre-fill agreements with that data, and write results back to Wealthbox after signing.
To use the integration, first create a workflow in Docusign.
Log in to Docusign and go to Agreements → Workflows.
Click Create Workflow.
Build your workflow using the available steps, including the Wealthbox actions provided by the app.
Publish the workflow when it is ready.
Once the app is installed and connected, its actions appear in the step picker. Click + Add Step and search for Wealthbox:
A typical agreement flow: Read the client's contact → pre-fill the envelope → collect signatures → Writeback any updated details.
The Read from Wealthbox step retrieves a single record (Contact or Opportunity) from Wealthbox and exposes its fields as workflow variables for pre-filling an envelope, driving conditions, or feeding a later Writeback.
In this example the workflow starts From an API Call and receives the ID of the record to read, so an external system can trigger it and tell it which Wealthbox record to use.
Select a method: choose From an API Call.
Set up variables: add a Text variable named object_id. The external system passes the record's ID into this variable when it triggers the workflow.
Process type: choose Automated process, since another system (not a person) makes the API call.
Once published, the workflow has a URL your external system calls (GET or POST), passing object_id. The Read step uses that value to look up the exact Wealthbox record.
On the workflow canvas, click + Add a step below Start Workflow.
Search for Wealthbox and select Read from Wealthbox.
Connection: select the connection you created during installation, for example "Wealthbox-Connection-1 (Shared)".
Wealthbox object: choose the record type. Two are available, Contact and Opportunity; this example uses Contact.
Click Next.
Click Add or Remove Fields and tick the fields your workflow needs; you don't have to select them all. The selected fields become workflow variables for later steps.
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, 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, Assigned To 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.
Click Next.
Create a rule that tells the step which record to read. In this example, match the Wealthbox Record ID to the object_id variable from the workflow start:
object_idUnder How many records should this step return?, keep A single record. The step returns the first record that matches. Click Apply.
You can also match on other identifiers. For Contacts: Record ID, First + Last Name (exact), or Email. Matching by Record ID carried from the trigger is the most reliable, because it resolves the exact record.
⚠️ Name conditions match exactly: "Kev" won't match "Kevin". With A single record selected, the step takes the first match, so match by Record ID when you need one specific record.
The Writeback to Wealthbox step creates or updates a Contact or Opportunity from workflow data: signer-entered form fields, envelope metadata, or values carried from a Read step. It is typically the last step, after signing completes.
On the workflow canvas, click + Add a step where you want the writeback, for example below a Collect Data with Web Forms step.
Search for Wealthbox and select Writeback to Wealthbox.
Connection: select your Wealthbox connection (the same one you created during installation).
Wealthbox object: choose the record type, Contact or Opportunity (this example uses Contact).
Write settings: choose how the step handles the data:
Click Next.
Click Add or Remove Fields, then map each Wealthbox field to the workflow variable that supplies its value.
⚠️ Map from the right source. The picker also lists variables from your Read from Wealthbox step. Mapping from the Read step would write the original values back unchanged. For a writeback that saves the signer's input, map from the collected data (for example, here the Collect Data with Web Forms step).
Writable fields:
Contact (write): First Name*, Last Name*, Middle Name, Nickname, Prefix, Suffix, Company Name, Job Title, Contact Type, Contact Source, Status, Marital Status, Gender, Birth Date, Client Since, 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 Name*, Assigned To Name, Next Step, Amount*, Amount Kind, Linked Contact (ID or Name).
* required on create.
Click Next.
Create a rule that tells the step which record to write to. In this example, match the Wealthbox Record ID to the Record ID collected in the form:
Click Apply.
The walkthrough above updates a Contact; the same pattern updates an Opportunity, and updates are supported for both. Three settings differ:
Record ID.Map the fields that should change, for example Stage Name and Amount after a signed engagement:
Remember to keep all required fields (marked *) mapped.
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, so partial copies are the usual cause) and try again. If your Wealthbox admin revoked the token, create a new one.
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 instead of risking the wrong deal. Match opportunities by Record ID.
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 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.
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: Make sure you've filled every required field. An opportunity needs Name, Stage Name, Probability, Amount, and Target Close Date; it won't create without all of them.
Q: Can I upload the signed PDF file into Wealthbox?
A: Not yet. Wealthbox's public API doesn't currently offer a file-upload endpoint; as soon as that becomes available, we'll add support for it.