How Sector Growth scopes a HubSpot integration in five stages

We read the source system and find out what it can actually do. Not what the documentation claims: what live API responses return when you call them.

That means testing the endpoints the design would depend on, counting the objects, agreeing the direction each one moves, and writing down what a record has to look like on both sides. It also means finding the fields that do not exist. On one publisher’s build, discovery checked 79 source properties against live responses before any flow was designed. Of those, 49 mapped directly, 23 needed a transform or a second call, and 7 exist nowhere in the source, which became a documented omission rather than a surprise during user acceptance testing.

Two answers matter more than the rest, and they are the ones teams skip. Can the source tell you what changed since a timestamp, and does it raise webhooks? A no to both does not stop the project, but it changes the architecture and the estimate, so it belongs here rather than in week six.

You receive a scope note with the object list, the match keys and an effort band.

We need read access or credentials to a real environment, and one person who can decide what is in scope. Discovery runs 4 to 8 hours for a native app or a packaged sync, 6 to 12 for a light custom build, 10 to 20 for a standard two way sync, and 20 to 40 for an enterprise build spanning several systems.

We pick the pattern, design the HubSpot object model, and decide which side owns each record. Ownership is the decision that prevents the worst class of bug, where two systems take turns overwriting the same field forever.

Match keys are settled here. Every object keys on the source system’s own identifier, held in a custom HubSpot property that HubSpot enforces as unique, never on an email address and never on a name. Names change when somebody tidies a record. One email address can belong to several people.

Two useful habits belong to this stage. Build the mapping outward from an exclusion list where the source carries fields that must never reach a marketing system, which is how we designed a senior living operator’s sync. And decide which values the sync is allowed to write before building any of it. On a manufacturer’s nightly sync, the source can prove only four of the ten deal stages the sales team uses, so the sync writes those four and never touches the six a rep sets by hand. A deal moved to artwork approval yesterday is still there after tonight’s run.

You receive an object model and a field mapping sheet, plus the architecture diagram.

We need a HubSpot super admin who can create properties and custom objects, and an hour from whoever knows why the source data looks the way it does.

We build against a sandbox portal, never against production. HubSpot API paths are pinned to version 2026-03, so a platform change cannot alter behaviour underneath a running service.

Everything is keyed and idempotent. Each object upserts on its source identifier, so running the same window twice changes nothing that already landed correctly. Where the source cannot report changes, the service keeps the memory itself: a watermark per flow, a checkpoint written after every run, and a replay path an operator can trigger. A window with no records still advances the watermark. A window where every lookup failed holds it instead of skipping quietly past data nobody read.

Associations run as a pass of their own, after the writes, from identifiers resolved out of the responses rather than guessed. Anything that fails to resolve queues for repair instead of disappearing into a log.

Rate limits are the constraint people underestimate, because HubSpot counts them per app rather than per user. So reads are cached where the same record is fetched repeatedly, large steps get admission control, and a step that bursts through the read budget is followed by a wait rather than a failure.

You receive a working sync in a sandbox, with the code and the runbook in their own repository.

We need a sandbox portal and source credentials for it, plus the API scopes the load actually needs, requested at provisioning. A phase that stops halfway because a private app is missing a scope is an avoidable pause.

Validation is not a demo. It is a reconciliation, a set of deliberately broken runs, and a walk through the portal with the people who will use it.

We compare record counts on both sides, object by object. We check that associations landed. We run the failure paths on purpose: a bad payload, a connection that never opens, a second full run to prove nothing duplicates. A sandbox validation run on one distributor’s migration settled five behaviours that documentation alone had not, and three of the answers changed the loader. Meeting any of them during a production run would have cost a rollback.

Cutover rehearsal belongs here too. On a financial services build, go live began with a full snapshot of the production account, then an automated schema comparison that found five properties missing from one custom object and created them before any write. The 137 files already processed in the sandbox were then re-driven through the production pipeline in batches of 10, with counts read back after each batch. All 137 completed with no failures.

You receive a reconciliation report, a user acceptance pass and a sign-off list.

We need two or three people who will use the data daily, for an hour each, and a decision on the sign-off list. Reconciliation questions are usually the fastest to answer and the most valuable.

Cutover is a token swap. The same code that ran against the sandbox is pointed at production, behind a portal allowlist that fails the run closed when the connected portal is not the one the environment expects. Nothing is rewritten for production, because rewritten code is untested code.

Then we watch the first runs, which is where the real operating knowledge appears. One nightly chain moved its run window after a long night ran into the client’s own overnight maintenance window. One step now waits 15 minutes after the largest upsert, because that step bursts through the portal read budget. Neither of those is something you can design in advance.

Operations is an interface, not a person remembering. That usually means health and state endpoints, a manual trigger, replay for a single run, and run history, so “did everything land” is a question an endpoint answers. On the handover side, the destination is either a service we watch or a service you own outright. One franchise sync transferred completely in September 2026: the client holds the server, the repository and the tokens, and the machine we had been running was destroyed after eight days of green runs on theirs.

You receive a live integration, monitoring, and a named person to call when it breaks.

We need a decision on who owns it after go live, and someone on your side who reads the alerts.

Elapsed time runs longer than the build hours, because it includes your reviews, access requests and sign-offs. These bands assume you can answer questions and grant access in the same week.

The stage that slips is almost always Scope, and almost always because access to a real source environment took three weeks to arrange. Start that request on day one.