Switching from Wealthbox
How a Wealthbox book moves into WealthY with one API token, field by field, and what stays behind.
WealthY reads your Wealthbox book directly from Wealthbox's own API: contacts, households, notes, tasks, events and opportunities. You paste one token, you review every field before anything is written, and the whole import can be rolled back in one click. The import never writes to Wealthbox. If you would rather keep Wealthbox, the hourly sync is a separate connection that does, keeping contacts, notes and tasks in step both ways; see Integrations.
What you need
- A Wealthbox login. Any user can create a personal API access token under Settings > API Access in Wealthbox.
- A WealthY firm owner login. The import lives on the firm side so every advisor's clients land in one place.
- About half an hour for a book of a few hundred households. Wealthbox allows roughly one request per second, so a very large book takes longer to read, not longer to review.
How the book leaves Wealthbox
- In WealthY, open Operations > Data and choose Wealthbox. During self-serve signup this is screen 3, Bring your data.
- Paste the token. WealthY's server uses it once to read your book and then forgets it; the token is never stored, never shown again and never used after the import.
- The read takes contacts (people, households, organizations and trusts), notes with their author and date, tasks, events, opportunities, your users and your tags.
Review before anything is written
The review screen shows your book as WealthY understood it, with the WealthY field printed beside every source field in the first rows, so you can see the mapping on your own data rather than in a table.
- Every person is marked client or prospect from Wealthbox's own contact type. Change any row. Clients get a client record; prospects go to the pipeline without a login.
- Every record gets an advisor: the Wealthbox owner where WealthY can match it to one of your advisors, otherwise the advisor you pick on this screen, who defaults to you. No import leaves a client without an advisor.
- Fields WealthY has no column for are not dropped. They are kept as a dated import note on the record, one per contact, so nothing you typed into Wealthbox disappears.
- Duplicates are checked against what your firm already has, by Wealthbox id first, then by email and phone. A repeat import matches instead of duplicating.
Commit, resume, roll back
- The import writes in short chunks and records where it got to. If the tab closes mid-way, open the page again and it continues; it never leaves half a book with no record of it.
- Everything the import created is linked to one batch. Roll back deletes exactly what that batch created and nothing else.
- Nobody gets a portal login from an import. You invite clients when you are ready, from People or from the record.
Field map and what is not imported
Every Wealthbox field WealthY reads, where it lands when the person is a client and when they are a prospect, and how the value is converted. Then the short list of what is deliberately not imported, and why.
Paste a personal API access token (Wealthbox, Settings, API Access). The token stays in your browser for the length of the pull, is used by our server to read contacts, households, notes, tasks, events and opportunities page by page, and is never stored.
Contact fields (80)
| Field in the source | Lands in WealthY | If the person is a prospect | How it is converted |
|---|---|---|---|
| id | crm_import_links.external_id | same | the Wealthbox contact id, so a repeat import matches instead of duplicating |
| prefix | kept as a note on the record | same | as written |
| first_name | clients.first_name | prospects.full_name (first part) | trimmed |
| middle_name | kept as a note on the record | same | kept as written in the import note |
| last_name | clients.last_name | prospects.full_name (last part) | trimmed |
| suffix | kept as a note on the record | same | kept as written in the import note |
| nickname | kept as a note on the record | same | as written |
| job_title | kept as a note on the record | prospects.title | as written |
| company_name | kept as a note on the record | prospects.company_name | as written |
| twitter_name | kept as a note on the record | same | kept as written in the import note |
| linkedin_url | kept as a note on the record | prospects.linkedin_url | as written |
| background_information | advisor_notes.content | prospect_notes.content | becomes a note titled Background |
| birth_date | clients.date_of_birth | kept as a note on the record | YYYY-MM-DD as Wealthbox stores it |
| anniversary | kept as a note on the record | same | kept as written in the import note |
| client_since | kept as a note on the record | same | kept as written in the import note |
| date_of_death | kept as a note on the record | same | kept as a note; the review screen flags the record |
| referred_by | clients.referred_by_name | prospects.referred_by_name | a contact id is resolved to that contact's name; an object yields its name; a plain name is kept as written |
| type | import record type | same | Person, Household, Organization, Trust. Households become households; the rest become people records |
| gender | kept as a note on the record | same | as written |
| contact_source | firm_custom_fields + client_custom_field_values ("Contact source") | prospects.source | as written |
| contact_type | clients.lifecycle_stage | kept as a note on the record | Client, Past Client, Prospect, Vendor and your own values; Client-like values become clients by the stage rule |
| status | kept as a note on the record | same | Active / Inactive, kept as a note |
| marital_status | kept as a note on the record | same | as written |
| attorney | kept as a note on the record | same | professional contacts are kept together in the note |
| cpa | kept as a note on the record | same | kept as written in the import note |
| doctor | kept as a note on the record | same | kept as written in the import note |
| insurance | kept as a note on the record | same | kept as written in the import note |
| business_manager | kept as a note on the record | same | kept as written in the import note |
| family_officer | kept as a note on the record | same | kept as written in the import note |
| assistant | kept as a note on the record | same | kept as written in the import note |
| other | kept as a note on the record | same | kept as written in the import note |
| trusted_contact | kept as a note on the record | same | kept as written in the import note |
| important_information | advisor_notes.content | prospect_notes.content | becomes a note titled Important information |
| personal_interests | kept as a note on the record | same | kept as written in the import note |
| investment_objective | kept as a note on the record | same | kept as written in the import note |
| time_horizon | kept as a note on the record | same | kept as written in the import note |
| risk_tolerance | clients.risk_profile | kept as a note on the record | as written |
| mutual_fund_experience | kept as a note on the record | same | kept as written in the import note |
| stocks_and_bonds_experience | kept as a note on the record | same | kept as written in the import note |
| partnerships_experience | kept as a note on the record | same | kept as written in the import note |
| other_investing_experience | kept as a note on the record | same | kept as written in the import note |
| gross_annual_income | kept as a note on the record | same | as written |
| assets | kept as a note on the record | prospects.estimated_aum when numeric | digits kept when it parses as a number |
| non_liquid_assets | kept as a note on the record | same | kept as written in the import note |
| liabilities | kept as a note on the record | same | kept as written in the import note |
| adjusted_gross_income | kept as a note on the record | same | kept as written in the import note |
| estimated_taxes | kept as a note on the record | same | kept as written in the import note |
| confirmed_by_tax_return | kept as a note on the record | same | kept as written in the import note |
| tax_year | kept as a note on the record | same | kept as written in the import note |
| tax_bracket | kept as a note on the record | same | kept as written in the import note |
| birth_place | kept as a note on the record | same | kept as written in the import note |
| maiden_name | kept as a note on the record | same | kept as written in the import note |
| retirement_date | kept as a note on the record | same | kept as written in the import note |
| signed_fee_agreement_date | kept as a note on the record | same | compliance dates stay with the record as a note |
| signed_ips_agreement_date | kept as a note on the record | same | kept as written in the import note |
| signed_fp_agreement_date | kept as a note on the record | same | kept as written in the import note |
| last_adv_offering_date | kept as a note on the record | same | kept as written in the import note |
| initial_crs_offering_date | kept as a note on the record | same | kept as written in the import note |
| last_crs_offering_date | kept as a note on the record | same | kept as written in the import note |
| last_privacy_offering_date | kept as a note on the record | same | kept as written in the import note |
| external_unique_id | kept as a note on the record | same | kept as written in the import note |
| occupation.name | kept as a note on the record | prospects.title | used when job_title is blank |
| occupation.start_date | kept as a note on the record | same | kept as written in the import note |
| email_addresses[] (principal) | clients.email | prospects.email | the principal address; Home before Work when none is principal |
| email_addresses[] (others) | kept as a note on the record | same | first extra address; the rest are kept in the note |
| phone_numbers[] (principal) | clients.phone | prospects.phone | the principal number |
| phone_numbers[] (kind Mobile) | clients.phone when phone is blank, else note | prospects.phone when phone is blank, else note | the Mobile number when it is not the principal |
| phone_numbers[] (others) | kept as a note on the record | same | every other number kept as "Kind: number" |
| street_addresses[] (principal).street_line_1 | clients.address | prospects.address_line1 | line 1; clients.address is the one-line address: line 1, line 2, postal code |
| street_addresses[] (principal).street_line_2 | clients.address | prospects.address_line2 | line 2 appended |
| street_addresses[] (principal).city | clients.city | prospects.city | trimmed |
| street_addresses[] (principal).state | clients.province | prospects.province | as written (ON, Ontario, NY all kept) |
| street_addresses[] (principal).zip_code | clients.address | prospects.postal_code | appended to the one-line address |
| street_addresses[] (principal).country | kept as a note on the record | prospects.country | as written; CA when blank for prospects |
| street_addresses[] (others) | kept as a note on the record | same | every other address kept as one line in the note |
| websites[] | kept as a note on the record | same | kept as written in the import note |
| tags[].name | firm_custom_fields + client_custom_field_values ("Tags") | prospects.tags | tag names joined with commas; the tag list itself is read from /v1/categories/tags |
| custom_fields[] (name, value) | firm_custom_fields + client_custom_field_values | firm_custom_fields + prospect_custom_field_values | one firm custom field per distinct name, created on first use; the value as written |
| contact_roles[] | kept as a note on the record | same | kept as "Role: name" in the note |
| created_at | clients.created_at | prospects.created_at | the original date, so the book does not look brand new |
Households (4)
| Field in the source | Lands in WealthY | How it is converted |
|---|---|---|
| household.id | households.external_id | one household per Wealthbox household id |
| household.name | households.name | as written |
| household.title | note on the member | Head, Spouse, Dependent kept as a note; the Head becomes households.primary_client_id |
| household.members[] | clients.household_id | every member client joins the household; member prospects carry the name in prospects.household |
Notes (6)
| Field in the source | Lands in WealthY | If the person is a prospect | How it is converted |
|---|---|---|---|
| notes[].id | crm_import_links.external_id | same | the source id, so a repeat import matches instead of duplicating |
| notes[].linked_to[] (type Contact) | advisor_notes.client_id | prospect_notes.prospect_id | the linked contact; a note on somebody who becomes a prospect lands on prospect_notes.prospect_id |
| notes[].content | advisor_notes.content | prospect_notes.content | as written, HTML stripped to text |
| notes[].created_at | advisor_notes.created_at | prospect_notes.created_at | the original date, so history stays in order |
| notes[].creator (via /v1/users) | advisor_notes.source_author | prospect_notes.source_author | the author name or email as written |
| notes[].tags[].name | advisor_notes.content | prospect_notes.content | appended as "Tags: ..." on the note |
Tasks (9)
| Field in the source | Lands in WealthY | How it is converted |
|---|---|---|
| tasks[].id | crm_import_links.external_id | the source id |
| tasks[].linked_to[] (type Contact) | advisor_tasks.client_id | the linked contact, or advisor_tasks.prospect_id |
| tasks[].name | advisor_tasks.title | as written |
| tasks[].description | advisor_tasks.description | as written |
| tasks[].due_date | advisor_tasks.due_date | to YYYY-MM-DD |
| tasks[].complete | advisor_tasks.status + completed_at | completed when the source says so, else pending |
| tasks[].priority | advisor_tasks.priority | low / medium / high / urgent; medium when unrecognized |
| tasks[].assigned_to | advisor_tasks.advisor_id | the owner mapped to an advisor, else the importing owner |
| tasks[].category | advisor_tasks.description | a numeric category id is resolved through /v1/categories/task_categories and prepended as "Category: name" |
Activities (calls, meetings, emails) (8)
| Field in the source | Lands in WealthY | How it is converted |
|---|---|---|
| events[].id | crm_import_links.external_id | the source id |
| events[].title | contact_log.subject | as written; a future, unfinished event becomes an advisor task instead |
| events[].starts_at | contact_log.contacted_at | the start time |
| events[].ends_at | contact_log.duration_minutes | minutes between start and end |
| events[].description + location | contact_log.notes | joined |
| events[].event_category | contact_log.contact_type | a numeric id is resolved through /v1/categories/event_categories; call / meeting / email / other by the name, meeting when unknown |
| events[].linked_to[] (type Contact) | contact_log.client_id | or contact_log.prospect_id |
| events[].state | skip rule | cancelled events are skipped and counted |
Deals and opportunities (10)
| Field in the source | Lands in WealthY | How it is converted |
|---|---|---|
| opportunities[].id | crm_import_links.external_id | the source id |
| opportunities[].name | deals.name | as written |
| opportunities[].description | deals.notes | as written |
| opportunities[].stage | deals.stage | a numeric id is resolved through /v1/categories/opportunity_stages, then mapped onto the pipeline by name; qualifying when unrecognized; the source name is kept in deals.notes |
| opportunities[].next_step | deals.notes | appended as "Next step: ..." |
| opportunities[].amounts[].amount | deals.value | the first amount |
| opportunities[].probability | deals.probability | 0 to 100 |
| opportunities[].target_close | deals.expected_close | the date part of the timestamp, YYYY-MM-DD |
| opportunities[].manager | deals.advisor_id | the owner mapped to an advisor |
| opportunities[].linked_to[] (type Contact) | deals.client_id | or deals.prospect_id |
Record owner (3)
| Field in the source | Lands in WealthY | If the person is a prospect | How it is converted |
|---|---|---|---|
| assigned_to | clients.advisor_id | prospects.advisor_id | the Wealthbox user id, resolved through /v1/users to an email, then to an advisor by email or name |
| users[].id, email, name | advisors.user_id | same | each Wealthbox user is matched to an advisor by email, then by name; unmatched users fall back to the advisor you pick |
| users[].status | skip rule | same | inactive and legacy users are still matched so their records land with the right advisor |
Not imported, and why
| Field in the source | Why |
|---|---|
| passport_number | Government ID numbers never travel in an import. They arrive through the document path, masked to the last four. |
| green_card_number | Same rule. |
| drivers_license (number, state, issued_date, expires_date) | Same rule. |
| image | Contact photos are not copied. The portal uses the client's own photo once they sign in. |
| creator, updated_at, visible_to | Wealthbox internals: who created the row in Wealthbox and who could see it there. The import note carries created_at only. |
| tasks[].repeats, tasks[].subtasks, tasks[].frame | Recurring task rules are not translated. The task itself lands once, with a note saying it repeated. |
| events[].invitees, events[].email_invitees, events[].repeats | Attendee lists and recurrence rules stay in the calendar you connect; the event lands as one history entry. |
| opportunities[].amounts[] beyond the first, amounts[].kind | deals.value is one number. Extra amounts are written into deals.notes. |
| Workflows, documents, email history | Not available through the Wealthbox API in a form that can be read without the firm's mailbox. Connect Gmail or Outlook to bring email history. |
After the import
- Open Contacts and spot-check ten households against Wealthbox.
- Connect each advisor's mailbox so email history comes from the mailbox itself; see Inbox.
- Drop statements, IDs and void cheques on the Data page's document step; each file is matched to its client for you to confirm.
- Continue with Getting started for firm owners.
Prefer a file? Export Contacts from Wealthbox as CSV and follow Switching from a spreadsheet. You get the same review screen; the token path simply brings more (notes, tasks, events, deals) in one pass.