Guide 01

Getting started

Connect a HubSpot portal, let the first company sync finish, and prove one small ZIP territory in read-only mode.

Last reviewed July 15, 2026 · Early-access documentation

Before you connect

  • Use a HubSpot user who can authorize apps for the selected portal.
  • Choose a developer test account or a portal where reading company country, ZIP, current owner, and owner records is acceptable.
  • Make sure a small set of test companies has a five-digit U.S. ZIP or ZIP+4 stored in HubSpot's standard company ZIP property.
  • 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. The OAuth callback creates an isolated Free workspace, makes the installer its Account Owner, and returns to the hosted console.
  4. If you leave, use Sign in to open the TerritoryLogic App Page inside the installed portal. The signed App Page launch creates a portal-bound session without reauthorizing the installation.

2. Follow the first sync

The initial sync discovers active HubSpot owners and stages a privacy-minimized snapshot for companies. It keeps the company record ID, current owner, normalized country and ZIP5, bounded validity 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. Watch the connection and initial-sync state. You may leave the page; the queued sync continues.
  3. If the sync reports a failure, use one manual full resync. If it fails again, stop and follow Troubleshooting.

3. Build a deliberately small program

  1. Open Programs & map and create a U.S. company ownership program.
  2. Leave enforcement on Recommend for the first test.
  3. Add one territory, enter one or two known ZIP5 values, and choose one active fixed HubSpot owner.
  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 company snapshot. It does not authorize a HubSpot change. Live publication is available only after the portal is separately approved for owner writes and reauthorized for the company-write scope.