CRM Owner Sync — Feature Overview

This guide explains, in simple terms, everything Topo does to keep record
ownership in sync with your CRM (currently HubSpot).

In one sentence: Owner Sync makes sure that whoever owns an account,
contact, or task in Topo is the same person who owns it in your CRM — and it
keeps them matched automatically, in both directions.

1. What "ownership" means

Every important record in Topo can have an owner — the person responsible
for it. Owner Sync covers three kinds of records:

The goal of Owner Sync is simple: the owner in Topo and the owner in your CRM
should always be the same person. If a sales rep owns "Acme Corp" in HubSpot,
they should own "Acme Corp" in Topo too — and vice versa.

Where an owner can come from

Topo remembers how a record got its owner, so it can make smart decisions:

• User — a person assigned it manually inside Topo.

• CRM Sync — the owner came from your CRM.

• Sequence assignment — Topo assigned it automatically as part of a sequence.

• System — Topo set it automatically. Today this happens when a teammate
  is removed from the organization: Topo clears that person off every record
  they owned so nothing keeps pointing at someone who's gone. This clear-out
  stays inside Topo and is not pushed to the CRM.

This "owner source" matters because Owner Sync treats a CRM-sourced owner
differently from one a user set by hand.

2. Mapping your users (CRM Settings)

Topo users and CRM users are two different lists of people. Before ownership can
sync, Topo needs to know which Topo user equals which CRM user. This is the
user mapping, configured in CRM Settings → Owners.

Automatic matching by email

When you connect a CRM (or click Refresh), Topo pulls the full list of
owners from HubSpot and tries to match each one to a Topo teammate by email
address. If the emails match, Topo creates the link automatically. These are
automatic matches.

Manual matching

Sometimes emails don't line up (a rep uses a different address in the CRM, for
example). An admin can open Owner Mappings and manually pick which Topo user
a CRM owner maps to. Manual matches are respected and survive future
refreshes — Topo won't overwrite a choice you made by hand.

What you can do on the Owner Mappings screen

• See every CRM owner and who they're mapped to in Topo.

• Refresh to pull the latest owners from HubSpot.

• Edit mappings one at a time or in bulk.

"Which CRM user do we push to?" (outbound default)

A single Topo user can occasionally be linked to more than one CRM owner record.
When Topo needs to send an owner to the CRM, it has to pick one. Topo
designates one mapping per user as the outbound default — the CRM identity
used when pushing changes out. If a user has exactly one mapping, that one is
the default automatically.

3. Turning Owner Sync on — activation & conflict policy

Owner Sync starts off. When an admin switches it on in CRM Settings, Topo
does a one-time backfill to get everything aligned before ongoing sync takes
over.

The first-time backfill

The moment Owner Sync is enabled, Topo sweeps through all of your existing
accounts and contacts (in batches) and, for each one, compares the Topo owner
with the CRM owner. For every record it decides one of:

• Push — send Topo's owner to the CRM.

• Adopt — pull the CRM's owner into Topo.

• Aligned — already matching, nothing to do.

• Blocked — the CRM owner isn't mapped to a Topo user yet (needs a mapping).

When it finishes you get a summary of how many records were pushed, adopted,
aligned, blocked, or skipped. (Activation requires exactly one active CRM
integration, and Topo first checks it can read owners from the CRM.)

Conflict policy — the tie-breaker

During that first backfill, some records will already have different owners
on each side. The conflict policy decides who wins. You set it per record
type — companies, contacts, and tasks each have their own:

• CRM wins (default) — keep the CRM's owner; adopt it into Topo.

• Topo wins — keep Topo's owner; push it out to the CRM.

Important: the conflict policy is mainly a tie-breaker for the initial
backfill. After activation, for accounts and contacts Topo does not
silently overwrite owners when the two sides later disagree — instead it flags
a Conflict for a human to resolve (see Sections 6–8). Tasks behave a little
differently (see Section 4).

4. Two-way (bidirectional) sync

Owner Sync works in both directions:

• Topo → CRM: Change an owner in Topo, and Topo pushes it to HubSpot.

• CRM → Topo: Change an owner in HubSpot, and Topo picks it up automatically.

How CRM → Topo works (HubSpot webhooks)

Topo doesn't have to constantly ask HubSpot "did anything change?" Instead,
HubSpot notifies Topo instantly whenever an owner changes, using a
webhook — a real-time message sent the moment something happens. Topo
listens for owner changes on companies, contacts, and tasks.

The flow, step by step:

1. Someone changes the owner of a record in HubSpot.

2. HubSpot fires a webhook to Topo saying "this record's owner is now X."

3. Topo checks that the new owner maps to a known Topo user.

4. Topo updates the matching record's owner in Topo.

Smart handling so nothing breaks

A naive two-way sync can create loops and chaos. Topo includes several
safeguards:

• No echo loops. When a change arrives from HubSpot, Topo updates its own
  record but does not bounce the same change straight back to HubSpot. This
  prevents an endless ping-pong.

• Debouncing (waiting a moment). If someone makes several rapid owner
  changes in HubSpot, Topo waits a short window (about 10 seconds) and only
  applies the final value, instead of reacting to every intermediate change.

• Ignoring out-of-date messages. Webhooks can arrive out of order. Topo
  stamps each record with the time of the latest change it has seen and
  ignores older, stale messages so a late-arriving old update can't undo a
  newer one.

Tasks work a little differently

Task ownership (the assignee) has its own switch — task owner sync only
runs when both task sync and the "sync task owner" option are turned on.

For tasks, Topo treats itself as the source of truth, so tasks never get stuck
in a manual conflict. When a task's owner changes in the CRM, Topo will:

• Adopt it onto the task assignee, or

• Re-push Topo's current assignee back to the CRM if the change would
  conflict (this follows the task conflict policy), or

• Leave the task untouched if the incoming owner isn't mapped to a Topo user
  (Topo never wipes an assignee because of an unmapped owner).

Because of this, the only task issues you'll ever see are Blocked (incoming
owner not mapped) and Failed (a push to the CRM didn't go through) — never
"Conflict" or "Pending."

5. Ownership during lead import

When you import leads into Topo, ownership can be assigned automatically from
the CRM — but only when both of these are true:

1. There is an active CRM connected, and

2. Owner Sync is enabled in settings.

If both conditions are met, here's what happens for each imported lead:

1. Topo looks up the lead's company in the CRM and finds its CRM owner.

2. Topo looks up the lead's contact in the CRM and finds its CRM owner.

3. If the contact has its own owner, that's used. If not, the contact
   inherits the company's owner.

4. The matched Topo user is set as the owner, marked as coming from CRM Sync.

Best-effort by design: if the CRM lookup fails for any reason, the import
still succeeds — the lead is simply imported without a CRM owner, and normal
assignment rules (like sequence assignment) take over. Owner Sync never blocks
or breaks an import.

If owner sync is off or there's no active CRM, this step is skipped
entirely and leads are assigned by Topo's normal rules.

6. Sync status — how Topo tracks each record

Every account and contact carries a sync status so you always know where it
stands:

The last two — Conflict and Blocked — are special: Topo will not
auto-resolve them, because doing so risks overwriting the wrong person's
ownership. An admin must resolve these (see Section 8).

7. Edge cases Topo handles for you

Owner Sync is built to behave sensibly in messy, real-world situations:

• Unmapped CRM owner. If a record's CRM owner isn't linked to any Topo user,
  Topo doesn't guess. It marks the record Blocked and waits until you add the
  mapping.

• Conflicting owners. If Topo says one person owns a record and the CRM says
  someone else does, Topo flags it as a Conflict instead of silently picking
  a side.

• Empty / cleared owners. If an owner is removed on one side, Topo can clear
  it on the other to keep them matched.

• A teammate leaves. When a member is removed from the org, Topo clears them
  off every record they owned (inside Topo only — see Section 1).

• Merged or deleted CRM records. If a company was merged or deleted in
  HubSpot, Topo notices the record is stale, skips it safely, and waits for the
  CRM data sync to re-establish the correct link — it doesn't error out.

• Rapid-fire changes. Handled by debouncing (Section 4).

• Out-of-order notifications. Handled by the timestamp watermark (Section 4).

• Already-correct records. If everyone already agrees, Topo does nothing (a
  "no-op") rather than making needless updates.

• Metadata drift. If the owner is right but some internal bookkeeping is
  stale, Topo quietly "heals" the record without changing the actual owner.

8. When something goes wrong — and how it's fixed

Automatic retries (reconciliation)

Topo runs a reconciliation process automatically in the background — once a
day in production (around 05:30 UTC). It scans for records stuck in Pending,
re-checks the live owner in the CRM, and tries to sync them again. This catches
anything that was temporarily missed — for example, because of a brief network
hiccup — without anyone having to lift a finger.

Reconciliation only retries Pending records. It deliberately leaves
Conflict and Blocked records alone, because those need a human
decision.

Manual resolution (for Conflicts and Blocked records)

Admins get a list of records that need attention (Conflicts and Blocked
items). For each one, they can choose how to resolve it:

• Keep Topo's owner — push Topo's owner out to the CRM.

• Adopt the CRM's owner — pull the CRM's owner into Topo.

• Clear the owner — remove the owner on both sides.

For Blocked records, the fix is usually simpler: add the missing user
mapping (Section 2), and the record can then sync normally.

Quick troubleshooting checklist

If ownership isn't syncing the way you expect, check, in order:

1. Is the CRM connected and active?

2. Is Owner Sync enabled in CRM Settings? (And for tasks, is "sync task
   owner" turned on?)

3. Is the user mapped? A missing or wrong mapping is the most common cause
   of Blocked records.

4. Is the record in Conflict? If so, resolve it from the attention list.

5. Give it a moment. Debouncing and the once-a-day reconciliation mean some
   changes apply after a short delay rather than instantly.

9. Glossary

Feature checklist (quick reference)

• Sync account, contact, and task ownership

• Map Topo users to CRM users (automatic by email + manual override)

• Activation backfill with a per-record-type conflict policy (CRM wins / Topo wins)

• Two-way sync via HubSpot webhooks (CRM → Topo) and pushes (Topo → CRM)

• Separate task owner toggle; tasks auto-resolve instead of conflicting

• Assign owners during lead import when an active CRM + Owner Sync are on

• Per-record sync status tracking (Synced / Pending / Failed / Blocked / Conflict)

• Loop prevention, debouncing, and out-of-order protection

• Automatic retries via once-a-day background reconciliation

• Manual resolution for conflicts and blocked records

CRM support: Owner Sync currently works with HubSpot. The system is
built on a provider abstraction, so additional CRMs (e.g. Salesforce) can be
added in the future, but they are not supported today.