Last reviewed: September 2026.

The Zoho integration copies data from your Zoho CRM into SurgeTK: households, clients, investment and bank accounts, beneficiaries, distributions, life insurance policies, other assets, liabilities, and tax years. You decide which Zoho modules and fields feed SurgeTK. The integration is one-way. SurgeTK reads from Zoho. Nothing is written to Zoho, and nothing is deleted in Zoho.

When you connect, SurgeTK asks Zoho for four read-only permissions: ZohoCRM.modules.READ, ZohoCRM.settings.modules.READ, ZohoCRM.settings.fields.READ, and ZohoCRM.users.READ.

The integration is available on every SurgeTK plan. Only SurgeTK Admins can connect it, map fields, run a sync, or disconnect it. Everyone at your firm can see the connection status, the sync progress, and the sync history.

Syncs are manual. SurgeTK never runs a Zoho sync on a schedule, and Zoho never pushes changes to SurgeTK. You sync when you want updated data.

Related: Sync Filters explains how to exclude households by client type and what happens to closed accounts. Syncing with Redtail covers the Redtail integration.

You need:

Know your Zoho setup before you map: which module holds households or families, which holds contacts, and which modules hold accounts, policies, assets, liabilities, and tax records. The owner field on an account, policy, asset, or liability module must be a lookup to Zoho's Contacts module.

The card now shows Connected and three buttons: Reconnect, Map Fields, and Sync. After a sync it also shows "Last successful sync:" with the time. The top bar shows a Zoho Connected badge and a Sync button. If your firm has both Redtail and Zoho connected, the top bar shows whichever CRM synced most recently.

If you close the Zoho window without finishing, the toggle turns itself off again after a short wait. Start again.

Click Reconnect on the card ("Reconnect Zoho to update permissions") to sign in to Zoho again, for example after a permission error. You see "Zoho reconnected successfully!". Your field mapping is kept. The next sync after a Reconnect is a full read of every mapped module, not only changed records.

Nothing syncs until you map fields. Click Map Fields on the Zoho card. The window is called Map Zoho Fields to SurgeTK. It says: "Map your Zoho modules and fields to SurgeTK. First pick a module for each tab, then map the fields below."

The window has eight numbered tabs, in this order: Households, Clients, Investable Assets, Bank Accounts, Insurance, Other Assets, Liabilities, Taxes. The window reopens on the tab you used last.

The Sync button on the card stays disabled, with the tooltip "Add at least one field mapping first", until at least one ordinary field is mapped on any tab. Choosing a module, a link key, or a lookup on its own does not count. Once a field is mapped, the tooltip reads "Start Zoho sync now".

Partial mapping is fine. Tabs with no module are skipped. Save does not enforce the required fields, so records that lack a required value are skipped when the sync runs. You can add fields at any time. After you add fields, run a Deep sync so records that did not change in Zoho pick them up (see Incremental syncs and Deep sync).

Pick "Zoho module for households", the module that stores your household or family records.

The Household Sync Filtering and Household Status Mapping sections on this tab decide which households sync and what happens to excluded or inactive households. See Sync Filters.

Pick "Zoho module for clients". Use Zoho's Contacts module: the owner lookups on the other tabs list only fields that look up to Contacts.

Client ID and the owner lookups must agree. The owner lookups on the Investable Assets, Bank Accounts, Insurance, Other Assets, and Liabilities tabs match their id value against the client's Client ID. The simplest setup is to leave Client ID on the Zoho record ID and set every owner lookup to id. If Client ID is mapped to your own client number, the lookups cannot find the owner by Zoho record ID, and every account, policy, asset, and liability gets a placeholder owner named "(Unknown) (Unknown)".

Pick "Zoho module for accounts", the module that stores investment accounts.

"Add one or more Zoho fields per allocation. Whole‑dollar rows are converted to % using the Account Total Value mapping above." There are four groups: Cash, Income (Fixed Income), Annuities, and Growth (Equity). Click Add field in a group, pick a Zoho field, and choose Percent or Whole $. You can add more than one field per group. A Whole $ row is divided by Account Total Value; if the account has no total value, that row is skipped. The result fills the account's asset allocation (Cash, Income, Annuities, Growth), which Buckets uses.

Distributions (separate Zoho module) reads a module that stores one row per distribution. Fields: "Zoho module for account distributions" (required); Parent (lookup to Accounts) with id or name, or Account Number field (fallback) when the module stores the account number in a plain field; Distribution Type; Gross Distribution Amount; Payment Date; Note (for One-Time & Estimated Tax); Federal Tax Withholding ($); State Tax Withholding ($). A dollar withholding on a row overrides the account-level percentage for that distribution. For the parent, SurgeTK tries both the id and the name, then the account number fallback.

The Distribution Type value decides what SurgeTK creates. Matching ignores capitalization, spaces, and punctuation, so "One Time", "one-time", and "ONE TIME" are the same value.

Deposits and contributions never come from this module. A recurring withdrawal created by the sync is removed again when its Zoho row is deleted, zeroed, moved to another account, or changed to a one-time type. Systematic withdrawals you entered by hand are not removed, with one exception: if a Zoho row matches a hand-entered withdrawal exactly, the sync adopts that withdrawal as its own and can remove it later.

Distribution History (monthly actuals ledger) is optional. Map it if your CRM keeps a ledger of what actually moved each month: one row per account per period, with a signed amount. Fields: "Zoho module for distribution history"; Parent (lookup to Accounts) or Account Number field (fallback); Signed Amount (required); Period Date (required); Tax Withheld ($); Note (optional).

Beneficiaries (separate Zoho module) reads a module with one row per beneficiary. Fields: "Zoho module for account beneficiaries" (required); Parent (lookup to Accounts) or Account Number field (fallback); Beneficiary Type; Beneficiary Name; Allocation (%); Beneficiary Date of Birth (optional); Beneficiary Relationship (optional). For the parent, SurgeTK tries both the id and the name, then the account number fallback.

Beneficiaries are replaced. Every account that has rows in the sync's feed gets its primary and contingent lists set to exactly those rows. Beneficiaries you added by hand to a Zoho-synced account are removed. Add them in Zoho instead. After you change beneficiaries in Zoho, run a Deep sync so every row for that account is read together; an ordinary sync fetches only rows that changed.

Pick "Zoho module for bank accounts". Use this tab for checking, savings, and similar cash accounts, and Investable Assets for custodial and investment accounts. The fields are the same as Investable Assets, except that Bank Accounts has an extra Ownership Type field and has no Asset Allocation, no Tax & RMD Annotations, and no Distribution History.

Fields: Owner field on Account (lookup to Contact) (required); Account Number (required); Account Total Value; Account Type; Tax Status; Custodian; External Household ID; 12/31 Value; Ownership Type; As Of Date; Federal Tax Withholding %; State Tax Withholding %; Close-out Filtering; Distributions; Beneficiaries.

Ownership Type marks joint accounts. When the value contains "joint" (or a variation such as JTWROS or TIC) and the household has exactly two members, both members become owners of the account. A value containing "joint" in Account Type does the same. With any other number of household members, only the looked-up owner is used.

Pick "Zoho module for insurance". Only life policies sync: the Policy Type value must contain the word "life". If Policy Type is not mapped, every policy is skipped.

Policy Status values are read like this. Capitalization does not matter.

Beneficiaries (separate Zoho module) for policies: "Zoho module for insurance beneficiaries" (required); Parent (lookup to Insurance) or Policy Number field (fallback); and the same five beneficiary fields as accounts. Rows without both a name and a percentage are skipped. Policy beneficiaries are replaced on each sync in the same way as account beneficiaries.

Pick "Zoho module for assets" for property, vehicles, collectibles, and other non-securities assets.

Pick "Zoho module for liabilities" for loans, mortgages, and credit accounts.

"Each Zoho Taxes record becomes one Tax Year row on the household's Taxes tab. Blank Zoho fields never erase figures entered in SurgeTK." Pick "Zoho module for tax years". Zoho is the only CRM that syncs tax figures into SurgeTK.

Rules: one Zoho record makes one tax year row, matched by the Zoho record first, then by household and year. A mapped field that is blank in Zoho keeps whatever SurgeTK already has. A value that cannot be read as a number is a field warning and does not overwrite. If Tax Year or Household (lookup) is not mapped, the whole Taxes stage is skipped without a message. When the first Zoho tax year arrives for a household, the older tax figures stored on that household are cleared, and its Taxes tab becomes the source for the Meeting Worksheet and the Roth conversion projections.

A toast says "Zoho sync started" and "Syncing data from Zoho. You can continue working." The sync runs on SurgeTK's servers. You can leave the page or close the tab. If nothing is mapped, the sync ends at once with "No Zoho modules are mapped. Nothing to sync."

Under Advanced, tick "Deep sync: re-check every Zoho record (slower). Also verifies records deleted in Zoho." The window adds: "Note: a deep sync skips closed-account cleanup — run an ordinary sync for that." A Deep sync reads every record of every mapped module, applies new field mappings to records that did not change, and flags records that no longer exist in Zoho. It also allows large advisor changes that an ordinary sync holds back. The box resets each time you open the window. Retry Sync on a result card always runs an ordinary sync.

Click Cancel on the progress card, then Cancel sync in the confirmation: "Cancel sync?" and "The sync will stop after the current step finishes. Data already synced will be kept." The button reads "Cancelling…" until the step ends. Records already written stay in SurgeTK. Nothing is rolled back, and the end-of-sync cleanup does not run. The card then offers Retry Sync and Dismiss, and the run is listed as Cancelled on the Imports page.

If nothing updates for 20 minutes, the card shows "Sync may have stalled" and "No updates received for 20 minutes", with Retry Sync and Dismiss. If SurgeTK restarts during a sync, the sync is marked failed ("Sync interrupted by server restart") and the lock is released within a few minutes. SurgeTK queues the interrupted sync again automatically about 10 minutes later.

A sync updates an existing SurgeTK record in place when it can match it. Otherwise it creates a new record.

Changing a household's link key value creates a new household on the next sync. Changing a Client ID creates a new client unless the email, or the name and date of birth, still match. When a record's number is already used by another record, the record is skipped and the result card says "N records need attention: they were skipped because other records already use their numbers". If your household link key is a name field and the household is renamed in Zoho, that household errors on every sync and the run is marked Partial. Use a stable ID field as the link key.

Every sync overwrites the fields it syncs. If you edit a mapped field in SurgeTK, the next sync that reads that record puts the Zoho value back. Make the change in Zoho. Fields you did not map are left alone. A mapped account field that is blank in Zoho is cleared in SurgeTK. A date SurgeTK cannot read counts as blank.

Household names are built from the household's clients, not from the Zoho household record. A Zoho household with no linked contacts appears as "(Unknown) Household" and is not removed automatically.

An ordinary sync asks Zoho only for records modified since your last successful sync finished. What each module reads:

What this means:

Map Lead Advisor on the Households tab to the Zoho field that names the household's advisor. On each sync, SurgeTK links that name to a SurgeTK user automatically when the email matches a user with an advisor seat exactly, or when the name matches exactly one user as "First Last" or "Last, First". Linked advisors become the household's lead advisors.

Names that cannot be matched wait for you:

Only Admins can link advisors, and the target must have the Lead Advisor role. A bell notification "Unlinked Zoho advisors" appears when new names arrive. While a household's Zoho advisor is unlinked, the sync keeps the household's previous advisor instead of leaving it empty. If more than half of your assigned households would change advisor in one sync, the removals are held back. A Deep sync applies them, unless more than nine in ten households would change. The Household advisors card in the Sync details drawer explains what was held.

Turn the Zoho toggle off. The Disconnect Zoho? window says: "Disconnecting will remove your saved Zoho connection and mappings. Data already imported into SurgeTK will remain." Click Disconnect. You see "Zoho disconnected."

Disconnecting:

Only Admins can use them. Ask an Admin at your firm.

Your browser blocked the Zoho sign-in pop-up. Allow pop-ups for SurgeTK and try again.

While mapping: "Your Zoho connection is missing permission to read modules (ZohoCRM.settings.modules.READ). Click “Connect to Zoho” to re-authorize and grant this scope." During a sync: "Zoho scopes missing (need ZohoCRM.settings.modules.READ). Click “Reconnect” on the Zoho card." There is no button called Connect to Zoho. Click Reconnect on the Zoho card and accept every permission. The same fix applies when the mapping window shows "Unable to load Zoho modules/fields."

You see "Zoho temporarily limited token refresh. Try again in ~Ns." or "Zoho token refresh limited; retry in ~Ns." Zoho refused to renew SurgeTK's access for the moment. Wait the number of seconds shown, then start again. A sync that hits this limit fails and does not retry by itself.

Its tooltip says "Add at least one field mapping first". Map at least one field on any tab and save.

An owner lookup on an account, policy, asset, or liability did not match any client's Client ID, so SurgeTK created a placeholder owner. Check that Client ID on the Clients tab holds the same value the owner lookups resolve to (see Clients tab). Fix the mapping, save, and run a Deep sync. SurgeTK replaces a placeholder when a client with that ID syncs.

Account Type must match a SurgeTK account type exactly, including capitalization. Change the value in Zoho, or leave Account Type unmapped and set the type in SurgeTK.

A date value SurgeTK cannot read counts as blank. Use a Zoho date field, or a text value in a standard date format.

SurgeTK makes an account joint only when the Account Type or Ownership Type value contains "joint" (or a variation such as JTWROS or TIC) and the household has exactly two members.

Deleting a Zoho-synced household in SurgeTK is not permanent. The next sync re-creates it. Archive it instead; a household you archived by hand stays archived. Or give it a client type that your exclusions skip.

SurgeTK names a household from its clients' names, not from the Zoho household record. Fix the client names in Zoho. A household with no linked contacts shows as "(Unknown) Household".

A household link key value or a Client ID changed in Zoho, or the link key is a name field that was renamed. See How records are matched. Pick stable ID fields for these keys.

An ordinary sync cannot link beneficiary or distribution rows whose parent account did not change since the last sync. Run a Deep sync.

Open the Skipped distribution rows card in the Sync details drawer. Rows are skipped when the Distribution Type is not one of the accepted values, the amount is zero or less, a one-time or estimated tax row has no Payment Date, or the parent account cannot be found.

Only policies whose Policy Type contains "life" sync. If Policy Type is not mapped, no policy syncs. Policy beneficiary rows need both a name and a percentage.

Both Tax Year and Household (lookup) must be mapped, or the Taxes stage is skipped. A record whose year is before 1990 or after next year is skipped. Unrecognized filing statuses and unreadable numbers are field warnings, shown in the Tax years row of the Sync details drawer.

Another sync or a data import is running for your firm. Wait for it to finish. If a sync was interrupted, the lock clears itself within a few minutes.

Zoho limited how many records SurgeTK could read from that module in one pass, so some records did not sync. Run the sync again later, as the card suggests.