The Connect dialog asks for Redtail Username and Redtail Password. SurgeTK then sends one GET /authentication with HTTP Basic authentication.

The Basic credential is the triple apiKey:username:password, base64-encoded. apiKey is SurgeTK’s own Redtail API key for that environment. Firms never see or enter it. There is one key for Production and one for Development.

On success SurgeTK stores the returned user key (authenticated_user.user_key).

Every later call sends Authorization: Basic base64(apiKey:username:password) and a userkey request header with the stored user key. The Basic value is rebuilt for each sync from the decrypted password.

The password is encrypted at rest with AES-256-GCM. A random 16-byte IV and the authentication tag are stored with the ciphertext. The username, the user key, and the environment are stored unencrypted, per firm.

Timeout: 30 seconds per request, for /authentication and for every call made during a sync. The three filter option lists use a 15-second timeout and are not retried.

Credentials are validated only when a firm enters them (Connect or Reconnect). SurgeTK does not probe credentials between syncs. A sync reuses the stored user key. If Redtail answers 401 on any call during a sync, the run is marked failed and the firm must reconnect. See Errors during a sync below.

A 403 on a single record does not count as a credential failure. Only 401 does.

After a credential failure the Integrations card shows Action needed and "Redtail rejected the saved login (<error>). Syncing is paused — reconnect with your current Redtail credentials to resume." The progress card offers Reconnect Redtail with the hint "Update your Redtail password if it changed, then reconnect below. No data was lost."

The server does not block a new sync in this state. The Sync button still starts one. A sync started with rejected credentials fails again with the same 401 message.

Reconnecting replaces the stored credentials, fetches a new user key, clears the credential error, and clears the sync watermark. The next sync is a full read. Sync Filters are kept.

The controls are visible to every role: the Redtail toggle, Connect, Sync Filters, Sync (on the card and in the header), and Cancel or Retry Sync on the progress card. The server refuses a non-admin click with HTTP 403 and the message "Forbidden: This action requires administrator access. You have <level> access." (for example "lead advisor access"). For Sync the browser shows that text raw, for example Error: {"message":"Forbidden: …"}.

Rate limit: one user can start at most 10 syncs in 5 minutes. Further attempts get HTTP 429 with "Too many requests. Please slow down and try again."

Every user in the firm sees the progress card and the sync toasts, whoever started the sync.

GET and HEAD requests are retried on HTTP 429, 500, 502, 503, and 504.

Up to 5 retries per request. The wait before retry N is min(1000 × 2^N, 15000) milliseconds plus a random 0 to 500 milliseconds: about 2 s, 4 s, 8 s, 15 s, 15 s.

Each request times out after 30 seconds.

The three option-list calls (/lists/contact_categories, /lists/contact_statuses, /lists/account_types) use a 15-second timeout and are not retried.

Contact notes, activities, tasks, or workflows.

Contact-level user-defined fields. Only the two account-level UDF endpoints above are tried.

Contact photos. GET /contacts/{id}/photo exists in the integration but is disabled.

Insurance or policy endpoints. The sync creates no insurance records. Everything Redtail returns as an account becomes a SurgeTK account.

Cost basis, tax lot, or performance endpoints.

Any POST, PUT, PATCH, or DELETE. Nothing is written back.

Webhooks. SurgeTK does not register or consume Redtail webhooks.

Every sync is manual. Sync in the header or on the Integrations card opens Confirm Redtail Sync. Sync Now starts it. There is no schedule, no auto-sync setting, and no webhook trigger.

The request claims the firm’s writer lock, stores the Re-read every contact flag when it was ticked, then queues a job for the background CRM sync workers. Each worker runs one sync at a time, so a queued sync can wait behind other firms’ syncs.

One lock per firm is shared by Redtail syncs, Zoho syncs, and spreadsheet imports. A second request while the lock is held gets HTTP 409 with "A Redtail sync is already in progress. Please wait for it to finish." The first words change to "A Zoho sync", "A data import", or "Another operation" depending on what holds the lock. The browser shows this JSON raw.

A spreadsheet import started during a sync gets HTTP 409 with "A Redtail sync is currently running for your firm. Please wait for it to finish before starting an import."

During a sync, edit forms in SurgeTK warn: "Heads up — a sync is running. Your changes might get overwritten when it finishes."

The worker writes a heartbeat every 30 seconds while the sync runs.

A sweep runs every 60 seconds on each web server. It clears any running sync whose heartbeat is older than 2 minutes and records "Sync interrupted by server restart". A crashed sync therefore releases the lock about 2 to 3 minutes after the crash. The one-time sweep at server start uses a 5-minute cutoff.

A queued sync that no worker picks up is cleared after 60 minutes with "Sync never started — the sync queue appears to be stalled".

A job whose worker died is re-run automatically about 10 minutes later, when its queue lock expires. The retry re-acquires the firm lock and runs visibly.

Cancel on a sync whose heartbeat is older than 2 minutes force-clears it with "Sync cancelled — process was unresponsive".

In the browser, after 20 minutes without an update the card shows "Sync may have stalled" and "No updates received for 20 minutes", with Retry Sync and Dismiss. This is a display watchdog only. The server-side sync may still be running.

The server sends the Socket.IO event syncStateChange to every user of the firm. It carries the sync state: the active flag, type, phase, percent, step, message, record counts, and the last result. It drives the progress card: "Redtail Sync in progress", "Running for Xm Ys", "Step X of 5", "N of M", a progress bar, and Cancel. No percentage number is displayed.

Step messages: "Preparing your sync...", "Counting contacts...", "Counting households...", "Fetching Redtail settings...", "Getting your contacts...", "Organizing households...", "Pulling account data...", "Pulling account data... (N/M contacts)", "Wrapping things up...".

A second event, redtailSyncProgress with phase and percent, goes to the triggering user’s room. Nothing in the front end listens to it.

Toasts for everyone in the firm: "Redtail sync started" with "Syncing data from Redtail. You can continue working."; then "Redtail sync complete", "Redtail sync finished with issues", "Redtail sync failed", or "Redtail sync cancelled".

One bad record never stops the run. Errors are counted per record and the sync continues.

After a completed sync a banner reads "New data is available from the latest sync." with a Refresh button.

The sync history is on the Imports page. A cancelled run is recorded there with the status failed.

Cancellation is cooperative. The dialog reads "Cancel sync?" and "The sync will stop after the current step finishes. Data already synced will be kept.", with Keep syncing and Cancel sync. The button then reads "Cancelling…".

The cancel flag is checked at these points: after the contacts step, after the families step, before the household lifecycle pass, before the account step, every 25 contacts during the account enumeration, and before each batch of 100 account saves. It is not checked inside the contacts or families page loops.

Records already written stay. There is no rollback.

Afterwards the card shows "Sync cancelled" with Retry Sync and Dismiss.

Contacts and families are processed page by page, one record at a time.

In the account step, contacts are enumerated one at a time, and each contact’s account list is fetched in turn. Account saves (the detail call, the conditional calls, the save, and the beneficiaries call) run 5 at a time, in batches of 100, with a cancel check before each batch.

Only the contacts step can be incremental. Families are re-read on every sync. Every contact’s accounts are re-read on every sync.

Incremental: when a watermark exists, contacts are read with GET /contacts/search?updated_since=<watermark>. Full: no watermark (first sync, after Connect or Reconnect, after Disconnect), or Re-read every contact ticked.

The watermark is the time the run finished. It is written only when the outcome is completed, at least one Redtail call succeeded, and no call answered 401. Partial, failed, and cancelled runs keep the old watermark, so the missed window is read again next time.

Because the watermark is the completion time, a contact edited in Redtail while the sync was running can be missed. It is read again when it changes again, or on a full read.

Re-read every contact is a one-shot flag stored on the firm. Only a cleanly completed run clears it. A partial, failed, or cancelled full run leaves it set, so the next sync is full too. The checkbox is cleared each time the dialog opens. Saving Sync Filters does not set the flag; the dialog only recommends it.

A full read re-creates clients and households the firm deleted. SurgeTK keeps no record of a deliberate deletion. An incremental run also re-creates a deleted client when that contact changes in Redtail.

With entries, matching is exact, case-insensitive, and trimmed on both sides. Allowlist: the value must equal one entry. Denylist: the value must equal no entry.

Categories with no entries: the smart default applies in both modes, and the allowlist/denylist switch is ignored. The category must contain the text client and must not contain ex-client or trust client. This is a substring test: "A Client", "Personal Client", "Former Client", "Prospective Client", "Non-Client", and "Ex Client" (no hyphen) pass. "Ex-Client" and "Trust Client" do not. A blank category fails.

Statuses with no entries: every status passes.

Blank values with entries: an allowlist excludes a blank category or status; a denylist includes it.

Both gates must pass. The category gate runs first.

Category source: category, then category_type, then contact_record_type (first non-empty). Status source: status, then status_name.

Hard filters, in every mode: a contact whose type is exactly "Business", and a contact with deleted set to true, never sync. Accounts of Business contacts are never fetched.

Filters gate new imports only. A contact that already has a SurgeTK client record (matched by Redtail ID) keeps updating when it is read, even when it now fails the filter. Its accounts are still fetched. A filter change never deletes anything.

Candidates: contacts read in this run that failed the category or status gate. On an incremental run these are only contacts changed since the watermark.

The contact must belong to a Redtail family (from GET /families?family_members=true) that already contains at least one SurgeTK client.

The category filter is bypassed completely, even for a category the firm deny-listed.

The status filter is applied only in denylist mode. An allowlist is not applied to family members. A member that already has a client record is updated even if its status is deny-listed.

Every family member qualifies: spouses, children, grandchildren, parents. There is no relationship-type filter. A status denylist is the only way to keep a family member out. See Why do children or other family members appear in my households?.

Business and deleted contacts stay excluded.

Imported members are attached to the family’s household, and their accounts are fetched in the account step.

Effective action: an explicit action wins. With no stored action, enabled true means delete and enabled false means close. The default is disabled, so mark closed. In the Sync Filters dialog the choices are Mark closed ("Closed accounts stay in SurgeTK, marked closed. They leave AUM and Value Adds but keep their history. Manual and imported statuses always win.") and Delete (legacy) ("Closed accounts are removed from SurgeTK on every sync. Accounts you closed by hand or by import are never removed.").

Closed test: an account counts as closed when its normalized status is Closed, Transferred, or Inactive, or when it has any close date. A status-only closure with no date counts. Redtail statuses containing dormant or suspended normalize to Inactive, so they count too.

In both modes, an account that reads as closed is left out of AUM totals and Value Add reports. The Hide closed accounts switch is a display preference for household account lists only.

Mark closed mode: the account is saved with its status and close date. A change from open to closed, or from closed to open, stamps the status source as redtail and writes one audit entry. A status set by hand or by a spreadsheet import (status source manual or import) is never overwritten. SurgeTK still records what Redtail said in the raw status field, so the account page can show the disagreement.

Reopen rule: only a Redtail status that normalizes to Active clears a stored close date. Pending, Other, and blank statuses never reopen a closed account. A close date from Redtail always wins.

Delete mode, before accounts are fetched: every stored Redtail-linked account that reads as closed is permanently deleted in bulk, removed from its household, and the household totals are recalculated.

Delete mode, per account: each account Redtail reports as closed is deleted if it exists in SurgeTK, and it is not imported.

Delete mode exemptions: accounts whose status was set by hand or by import are kept and still updated (except their status and close date). Accounts with no Redtail account ID (created by hand or by spreadsheet) are never touched. A Redtail account later updated by a spreadsheet import keeps its Redtail ID and is not exempt.

Close date sources, in order: close_date, closed_date, date_closed, termination_date, read from the account list item, then from GET /accounts/{id}. If there is still no date, the account reads as closed, and the firm is not in delete mode, SurgeTK calls GET /accounts/{id}/details once for that account. That probe stops for the rest of the run after the first 404, or after three consecutive other failures. Dates are parsed as standard dates first, then as 8-digit YYYYMMDD or MMDDYYYY strings. A year outside 1900 to 2100 is dropped.

Modes: Off (the default), Suggest, Automatic. Dialog descriptions: "SurgeTK never changes household status from Redtail." / "Syncs suggest archiving households whose members are all deceased or no longer clients. You review each suggestion on the Households page." / "Syncs archive those households automatically, capturing final Value Add snapshots. A status you set by hand always wins, and restoring is one click."

Status map: each Redtail contact status can be set to Default, Active client, No longer a client, or Deceased. Entries match by status ID first, then by name (case-insensitive, trimmed).

Default reading for unmapped statuses: a status matching /deceased|dead|death/i reads as deceased; a status matching /inactive|former|ex-|terminated|archived|closed|estate/i reads as no longer a client. The deceased test runs first. A blank status has no opinion.

Client flag: each time a contact is read, its deceased/living flag is rewritten from this reading to "Deceased" or "Living". A flag set by hand flips back to "Living" unless the Redtail status reads as deceased.

The household pass runs after the households step, for households with at least one Redtail-synced member. All members deceased: archive, reason deceased. All members deceased or no longer a client, with at least one merely no longer a client: archive, reason terminated. Any other member, including a member added by hand, keeps the household active.

Suggest: writes a suggestion on the household. The Households page shows "Redtail suggests archiving this household" and the row menu offers "Apply Redtail suggestion…". A dismissed suggestion is not raised again while the reading is unchanged. Suggestions that no longer apply are removed.

Automatic: archives at most 25 households per sync, minting final Value Add snapshots, and restores a household it archived itself when the reading returns to active. A household status set by hand or by import always wins. Setting the mode to Off removes outstanding suggestions. See Archiving households and closing accounts.

Closed accounts in delete mode, as above.

Emptied households: when a client is moved into its Redtail family’s household, the household it leaves is permanently deleted if no clients remain in it, unless that household is archived. This runs every sync and applies to any household, not only solo households. Records still attached to the deleted household are not moved by that step. Redtail-linked accounts are re-pointed to the new household in the account step.

Household archiving in Automatic mode, as above.

Broken links: a client whose household no longer exists loses the link and gets a solo household.

The sync never deletes a client. Contacts deleted in Redtail are skipped, not purged. Accounts that no longer appear in Redtail are only logged, never deleted. A filter change never deletes anything.

A contact in no Redtail family gets a solo household whose Redtail family ID is SOLO-<contactId>.

Household membership follows Redtail. Moving a Redtail family member, or a Redtail account, to another household by hand is undone on the next sync.

Beneficiary records are firm-wide and shared across accounts. The upsert key is the firm, plus first name and last name (compared case-insensitively), plus date of birth when Redtail supplies one. The unique index is (firmId, firstName, lastName, dateOfBirth).

The account’s primary and contingent tiers are replaced on every sync. When Redtail returns no beneficiaries, or the beneficiaries call fails, both tiers are emptied. Beneficiaries added by hand on a Redtail-synced account are therefore replaced.

The per stirpes flag and the "intentionally none" flag on the account are never touched by the sync.

A pair is stored only when both the amount and the frequency are present. The amount may be 0. The frequency then goes through the frequency normalizer.

A non-empty result replaces the stored withdrawals, including withdrawals entered by hand. An empty result never clears stored withdrawals.

Look-back: transactions with date_from set to 540 days before the sync.

A transaction counts as a withdrawal when its type, action, or transaction_type_description contains withdraw, distribution, dist, rmd, swd, or systematic; or its description contains withdraw or distribution; or its amount (amount, net_amount, or total) is negative. Any one condition is enough.

Date: date, trade_date, settlement_date, posted_on, or created_on, first present.

At least 3 withdrawals are needed. They are grouped by absolute amount to the cent. A group needs at least 3 entries.

Frequency from the median gap between consecutive dates in the group: 45 days or less is Monthly; 120 or less is Quarterly; 220 or less is Semi-annual; otherwise Annually.

One stream per frequency is kept: the largest amount wins.

A stream whose annualized total exceeds the account value is dropped (when the value is above 0).

The transactions endpoint is switched off for the rest of the run after a 404 on page 1.

Matching is by Redtail ID only. Clients, households, and accounts created by spreadsheet import before Redtail was connected are not merged. The sync creates a second record.

The keys do not include the environment or the Redtail database. Switching between Production and Development, or between Redtail databases, can attach records to the wrong Redtail IDs.

Reconnecting to the same Redtail database matches the existing records. No duplicates are created.

Disconnect dialog: "Disconnect Redtail?" with "Disconnecting will remove all saved Redtail credentials from SurgeTK. All data imported from Redtail will remain. You can reconnect later by toggling Redtail back on and re-entering your credentials." Buttons Cancel and Disconnect. Toast: "Successfully disconnected Redtail."

What Disconnect clears: the API key, user key, username, encrypted password, environment, and the sync watermark. It also clears everything else in the firm’s Redtail settings: the Contact Categories and Contact Statuses filters, the Closed Accounts setting, Hide closed accounts, the status map, the Household Lifecycle mode, the cached option lists, the credential status, and the Re-read every contact flag.

What Disconnect keeps: every synced client, household, account, holding, and beneficiary, with their Redtail IDs; advisor records and advisor links.

Reconnect without disconnecting (Connect again, or Reconnect Redtail after a credential failure): merges into the existing settings. Filters are kept. A new user key is fetched, the credential error is cleared, and the watermark is cleared, so the next sync is a full read.

After Disconnect and then Connect: the filters are back to their defaults, the next sync is a full read, existing records match by Redtail ID, and households or clients the firm deleted come back.

Purge guard: if the households hold Value Add snapshots or surge packets, the server refuses with HTTP 409. The user sees "Delete permanently?" with a message such as "2 Value Add snapshots and 1 surge packet become unreachable if this household is deleted. Archiving keeps everything and hides it from lists." and the buttons Archive instead and Delete anyway. For a household that is already archived, the dialog offers only Delete anyway.

Deleted with the household: its clients; every account in the household or owned by those clients, including accounts that sit in other households; liabilities in the household or owned by those clients; assets owned by those clients; insurance that belongs to the household or where a client is the owner or the insured; the household’s Value Adds and their snapshots; unlinked Redtail advisor directory rows referenced by the household or its clients (linked advisors stay).

Not deleted: Beneficiary records (they live in the firm-wide list); surge packets (left behind, no longer reachable from a household).

A later full read, or a change to one of those contacts in Redtail, re-creates the household, its clients, and its accounts. No index residue blocks the re-import.

Deleting a client is blocked while linked data exists: "Cannot delete client — linked financial data exists. Please reassign or delete their accounts, liabilities, assets, or insurance policies first." Deleting a household’s only client deletes the household.

Frequency values: SurgeTK maps only monthly, quarterly, semiannual, semi-annual, and annual (case-insensitive). annual is the only recognized yearly value. Other spellings are not mapped.

systematic_withdraw_amount, systematic_withdraw_frequency, and the payment block may be absent from account payloads on the current API. SurgeTK then depends on the transactions endpoint, which is switched off after a 404.

GET /accounts/{id}/user_defined_fields and GET /accounts/{id}/udfs answer 404 on the current API (verified July 2026). SurgeTK probes them once per run and then skips them.

GET /accounts/{id}/details and GET /accounts/{id}/transactions are called conditionally, each behind a circuit breaker. SurgeTK has not confirmed what they return on every tenant.

include and pagesize are honored only as request headers. updated_since is honored only on /contacts/search. SurgeTK is built for this.

Everything returned by GET /contacts/{id}/accounts becomes a SurgeTK account, whatever its type. Insurance products returned there become accounts.

company is usually empty on feed-linked accounts. SurgeTK uses feed_aggregator as the custodian.

Only beneficiary_type_description exactly "primary" reaches the primary tier.

Contacts flagged deleted are skipped but never purged in SurgeTK.

Redtail account statuses containing dormant or suspended read as Inactive, which counts as closed.

No webhooks. SurgeTK reads on demand only.

Syncing with Redtail

Sync Filters: control which CRM records come into SurgeTK

Why do children or other family members appear in my households?

Archiving households and closing accounts

Why a Client or Account Is Missing From a Report