Overview
Connecting SurgeTK with your Zoho CRM account lets you read (not write) data into SurgeTK using your own module/field mapping. After a one‑time setup, a manual sync will add new records and update existing ones based on your unique identifiers—saving time and reducing manual entry while keeping your model clean and consistent.
What this article covers
How to connect Zoho
How to map fields (required)
What data you can bring into SurgeTK
Unique identifiers & link keys (critical for clean re‑syncs)
Advanced mapping: beneficiaries, distributions, and asset allocation
Re‑mapping, re‑syncing, and troubleshooting
Read‑only & minimal scopes
SurgeTK only reads from Zoho. During connect you’ll grant the minimum scopes needed to read modules, module/field metadata, and users (e.g., Modules, Settings.Modules, Settings.Fields, Users). You can “Reconnect” at any time to adjust scopes or refresh the connection.
Getting Started
1) Open Integrations and connect Zoho
In the SurgeTK header, click Connect CRM to open the Integrations page.
On the Zoho card, toggle ON or click Connect.
Sign in to Zoho and grant the requested read‑only scopes.
If you run into a permissions prompt later, use Reconnect on the Zoho card.
Make sure your browser allows pop‑ups for the Zoho OAuth window.
2) Map your fields (required)
On the Zoho card, click Map Fields to open the Map Zoho Fields to SurgeTK modal.
Work through each tab:
Households, Clients, Investable Assets, Bank Accounts, Insurance, Other Assets, Liabilities.
Accounts have advanced sub‑sections for Beneficiaries, Distributions, and Asset Allocation.
Choose the Zoho module for each tab, then map the fields one‑by‑one.
For any lookup (e.g., “Owner (lookup to Contact)”), choose whether we should read the lookup’s id or its name (use the small sub‑field selector).
Save. The Sync button is enabled once at least one field is mapped. Partial mapping is OK—you can expand later.
Tip: If a perfect 1:1 field doesn’t exist, map the closest field that carries the data you need. You can always refine and re‑sync.
3) Run a sync & review
Start a sync from the Zoho card (Sync).
You’ll see a progress dialog with phase updates and percent complete.
A sync will:
Pull the latest data from the Zoho modules you mapped
Add new records that don’t exist in SurgeTK
Update existing records in place based on your unique identifiers
We do not delete unrelated manual data in SurgeTK. Only mapped fields are updated.
What You Can Bring In (by tab)
Below is a field‑level guide that mirrors the mapping modal. “Required” means SurgeTK needs that mapping for clean, repeatable syncs.
Households (Family Data)
Module: pick the Zoho module that stores households/families.
Required
Household ID (unique link key): stable external key used to group clients into families.
Optional
Lead Advisor
Marginal Tax Bracket (%)
AUM Billing (annual)
Additional Fees (household level)
Clients (Contacts)
Module: typically Contacts (or your equivalent).
Required
Household ID (lookup to Family): choose the client field that looks up to your Household module, then select id or name as the sub‑field.
Client ID: a stable external identifier; Record ID works if you don’t already track a client ID.
First Name, Last Name
Optional
Email, Phone Number, Birthday
Deceased / Living (or Date of Death)
Monthly Income, Occupation, Employer
Retirement Date, Gender
Note: Clients are the anchors for ownership lookups on accounts, insurance, assets, and liabilities.
Investable Assets (Accounts)
Module: pick your investment accounts module.
Lookups (required)
Owner (lookup to Contact): choose the accounts field that points to Contact; then pick id or name.
Core identifiers
Account Number (required): the unique key for the account. If you don’t have a dedicated field, use Record ID.
Optional fields
Account Total Value, Account Type, Tax Status, Custodian
External Household ID, 12/31 Value
Deposit Amount, Deposit Date
As Of Date (valuation date)
Advanced sub‑sections
Beneficiaries (separate Zoho module):
Link via Parent (lookup to Accounts) and choose id or name, or fall back by mapping an Account Number field stored on the beneficiary row.
Map Type, Name, Allocation (%), optional DOB, Relationship.
Distributions (separate Zoho module):
Link via Parent (lookup to Accounts) (id/name) or fall back by mapping the Account Number field.
Map Distribution Type, Gross Amount, Payment Date (used for One‑Time distributions).
Note: Frequency details for recurring distributions aren’t mapped today; capture the gross amount and type.
Asset Allocation (dynamic):
Add one or more fields under Cash, Income, Annuities, Growth.
For each field choose Percent or Whole $.
Whole‑dollar values are converted to % using Account Total Value.
Bank Accounts
Module: pick your bank accounts/cash accounts module.
Lookups (required)
Owner (lookup to Contact) with id or name.
Core identifiers
Account Number (required)
Optional fields
Account Total Value, Account Type, Tax Status, Custodian
External Household ID, 12/31 Value
Deposit Amount, Deposit Date
As Of Date (valuation date)
Advanced sub‑sections
Distributions: same linking and field options as Investable Assets.
Beneficiaries: same linking and field options as Investable Assets.
When to use:
Use Investable Assets for custodial/investment accounts. Use Bank Accounts for cash/checking/savings and similar non‑custodial accounts you want in cash‑flow and net worth views.
Insurance (Policies)
Module: pick your insurance/policies module.
Identifiers & lookups
Policy Number (required)
Insured/Owner (lookup to Contact) (required): choose id or name.
Optional fields
Carrier Name, Policy Type, Policy Subtype
Face Amount, Cash Value
Effective Date, Expiration Date
Premium Amount, Premium Mode
Beneficiaries (separate Zoho module)
Link via Parent (lookup to Insurance) (id/name), or fall back by mapping a Policy Number field on the beneficiary row.
Map Type, Name, Allocation (%), optional DOB, Relationship.
Other Assets (Physical/Non‑Securities)
Module: pick your other assets module (property, vehicles, collectibles, etc.).
Owner lookup
Owner (lookup to Contact): choose id or name. If you don’t have a true lookup, you can leave this unmapped and store an Owner ID in a plain field if needed.
Core identifiers
Asset Number (required)
Optional fields
Display Name, Value, Type
Liabilities (Loans, Mortgages, Credit)
Module: pick your liabilities module.
Lookups (required)
Owner (lookup to Contact) with id or name.
Core identifiers
Liability / Loan Number (required)
Optional fields
Type, Creditor Name
Interest Rate, Monthly Payment, Outstanding Balance
Estimated Payoff Date, Household ID (optional link)
Unique Identifiers & Link Keys
Stable keys ensure re‑syncs update the right records rather than creating duplicates. If your org doesn’t have a dedicated external key, you can map the Zoho Record ID.
Clients → Client ID (required): use a stable client identifier (Record ID is fine).
Households → Household ID (unique link key): used to group clients into families and link accounts to households.
Investable Assets / Bank Accounts → Account Number (required): the unique account key; fall back to Record ID if needed.
Insurance → Policy Number (required): uniqueness is enforced alongside firm and carrier.
Liabilities → Liability / Loan Number (required): uniqueness is firm + accountLoanNumber.
Other Assets → Asset Number (required): uniqueness is firm + assetNumber.
Tip: Map these first. Avoid changing them later; changing a unique identifier causes new records to be created on the next sync.
Re‑Mapping & Re‑Syncing
If a value didn’t come over, it’s almost always the mapping (field choice) or a data‑type/lookup sub‑field issue.
Try a different Zoho field or switch a lookup sub‑field (id ↔ name), save, and run a new sync.
Re‑syncs are safe: when your unique identifiers stay the same, SurgeTK updates in place.
You can start a sync anytime from the Zoho card; you’ll see phases and percent complete. If a permissions error appears, click Reconnect on the card to re‑authorize with the missing scopes.
Troubleshooting
Blank or wrong values
Recheck the mapped Zoho field. For lookups, try switching id ↔ name.
“Missing permission to read modules/fields”
Reconnect Zoho and grant read scopes (e.g.,
ZohoCRM.settings.modules.READ,ZohoCRM.settings.fields.READ).
“Temporarily limited token refresh”
Zoho has rate‑limited OAuth refresh. Wait briefly and try again—SurgeTK automatically backs off.
Sync button disabled
Add at least one field mapping and Save. The Sync action is enabled only when mapping exists.
Unexpected duplicates
Confirm your unique identifiers (Client ID, Account Number, Policy Number, etc.) haven’t changed. Changing them creates new records rather than updating existing ones.
Best Practices
Map unique IDs first to lock in stable updates.
Prefer true lookups (e.g., Parent → Accounts) when linking beneficiaries/distributions; only use the Account Number/Policy Number fallback if a lookup doesn’t exist.
Use Record ID where you don’t have your own external key.
Start with a minimal mapping, sync, inspect results, then expand mapping—iterate, don’t boil the ocean.
Keep Account Number consistent across systems to ensure clean merges with imported files and other data sources.
FAQ
Does SurgeTK write back to Zoho?
No. The integration is strictly read‑only.
Will disconnecting Zoho delete my data in SurgeTK?
No. Disconnecting only stops new reads from Zoho. Existing SurgeTK data remains.
How often does syncing run?
Syncing is manual (from the Zoho card). Run it anytime you need a refresh.
Does SurgeTK auto-sync my data from Zoho?
No, SurgeTK does not auto-sync data from Zoho. The only way to sync your data is to manually click the Sync button.
Where do beneficiaries come from?
From separate Zoho modules you designate for Accounts/Bank Accounts and for Insurance. Link them to the parent via a lookup (preferred) or fall back to an Account/Policy Number field stored on the beneficiary row.
Do you import recurring distribution frequency?
We capture Distribution Type, Gross Amount, and Payment Date (used for One‑Time). Frequency cadence fields aren’t mapped at this time.
Why This Matters
A thoughtful mapping eliminates repetitive entry and unlocks value across SurgeTK—net worth, beneficiaries, buckets/guardrails inputs, and more. Map what you can now, then refine and re‑sync as your Zoho evolves.