Guide 01

Getting started

Connect a HubSpot portal, choose one or more CRM objects and map each ZIP property, then prove one shared territory plan in read-only mode.

Last reviewed July 29, 2026 · Early-access documentation

Before you connect

  • Use a HubSpot user who can authorize apps for the selected portal.
  • Prefer a developer test account. If you use another portal, confirm that reading every selected object, its mapped ZIP property, current owner, and owner records is approved.
  • Make sure a small set of test records has a U.S. ZIP in an editable single-line text or number property on each object. Text may contain ZIP5 or ZIP+4; number values must be whole values from 0 through 99999.
  • Use a desktop or tablet viewport wider than 820 pixels to edit territories. Smaller screens can inspect the workspace but deliberately keep the editor read-only.
  • Know that HubSpot is the login. TerritoryLogic does not create a separate password.

1. Install with HubSpot

  1. Open Install free and select Install free with HubSpot.
  2. Sign into HubSpot, choose the exact portal, review the read scopes, and approve them.
  3. For a new installation, the OAuth callback creates an isolated Free workspace, makes the installer its Account Owner, queues the first routing snapshot, and redirects through a single-use launch into the hosted console.
  4. If the selected portal is already connected, HubSpot returns to the native TerritoryLogic App Page instead of creating another workspace. Select Open territory console on the App Page for a signed launch into the hosted console.
  5. If you leave later, use Sign in to return to that native App Page and launch the console again.

2. Follow the first sync

The hosted console can open while the queued initial sync is still running. Open Programs & map and wait for its status banner to say HubSpot routing snapshot ready before creating or simulating a program. TerritoryLogic discovers active HubSpot owners and stages privacy-minimized routing evidence for every selected object. It keeps object type and record ID, current owner, normalized country/ZIP5, bounded city/state fallback evidence, and the minimum configured filter facts. It does not retain raw street addresses or malformed ZIP input.

  1. Open Workspace settings and confirm the portal ID is the one you intended.
  2. Open Programs & map and watch the initial-sync banner. You may leave the page; the queued sync continues.
  3. Continue only when the banner says HubSpot routing snapshot ready.
  4. If the banner reports a failure, use one manual full resync from Workspace settings, then return to Programs & map. If it fails again, stop and follow Troubleshooting.

3. Build a deliberately small program

  1. Open Programs & map, select every HubSpot object that should share the territory plan, map each object's ZIP/postal property, and create the ownership program.
  2. Leave enforcement on Recommend for the first read-only test. Recommend calculates and publishes routing decisions, but it makes zero HubSpot owner writes.
  3. Add one territory, draw a small area on the map, review the whole ZIP areas TerritoryLogic selects, apply them to the draft, and choose one active fixed HubSpot owner. Manual ZIP entry remains available only as a fallback for ZIPs without a mapped Census area.
  4. Save the draft. If another editor changed it, reload rather than forcing the stale revision.
  5. Run a simulation and inspect every result category. Simulation is read-only.

4. Stop at the correct boundary

A successful simulation proves what the current saved draft would decide for the captured object-specific record snapshots. It does not authorize a HubSpot change. Live publication is available only after the portal is separately approved for owner writes and reauthorized for every selected object's write scope.

Publishing while the program is still in Recommend mode stores the plan, decisions, and evidence only. A result labeled No write — Recommend is expected and means the current HubSpot owner was not changed.

5. Run a deliberate owner-write QA test

Only continue with a disposable record in a developer test portal. In Workspace settings, first confirm the owner-write status says Guarded HubSpot writes ready. If it does not, stop; the portal must be approved and the Account Owner must complete the object-specific write reauthorization.

  1. Return to the program and change enforcement to Fill empty for a test record with no owner, or Enforce for a controlled reassignment.
  2. Save the changed draft and run a fresh simulation. Do not reuse the Recommend simulation.
  3. Open Review publish and confirm it says Live writes approved, shows the intended enforcement mode, and lists exactly the expected number of eligible writes.
  4. Publish once, then verify the disposable record's HubSpot owner and the TerritoryLogic Activity entry.
  5. If the result is protected rather than written, read the reason shown beneath the result before changing or retrying anything.