DataGrows × HubSpot
How the data flows
between our
systems
This document maps the ideal data flow between the DataGrows site, the backend, and HubSpot — so we can confirm what's technically feasible before locking in the full strategy.
01 — Architecture
System Data Flow
Three systems, two integration zones. The frontend → HubSpot connection is handled by us using HubSpot's tracking script and form embeds. The backend → HubSpot connection is the critical piece we need from the DataGrows Dev Team — a series of API calls fired from the DataGrows backend when key events occur.
User Browser / Site
DataGrows Backend
HubSpot
Direct
connection — handled by us
API
bridge — the critical piece
User
Browser / Site
DataGrows
Backend
HubSpot
⚡ API Bridge
① Tracking Script
Sets the
hutk cookie, tracks pages & ad
source — anonymously.
② Contact / Newsletter
HubSpot JS embed — native HTML, not an iframe.
③ Trial Registration
Stays as custom form. One hidden
hutk field,
added via GTM.
Account created
Receives the trial signup +
hutk. Creates the
user account.
Platform events
Subscription changes, milestones, cancellations.
Anonymous session
Session stored against the
hutk — before they
convert.
Contact created
Form submit → CRM contact. Session merges via the
hutk.
Contact created / updated
Trial contact + plan. Lifecycle →
Opportunity.
Journey updated
Timeline, lead score, lifecycle & workflows all fire.
tracking · hutk
form submit
submit
POST /contacts
POST events
⚡ What the API bridge carries — for the DataGrows Dev Team to
confirm
① Trial Registration
POST /crm/v3/objects/contacts
→ create / update contact with trial data + hutk
→ create / update contact with trial data + hutk
② Subscription Changes
POST /crm/v3/contacts/{id}
→ update status: paid / cancelled / upgraded
→ update status: paid / cancelled / upgraded
③ Platform Milestones
POST /crm/v3/timeline/events
→ log milestone events on contact timeline
→ log milestone events on contact timeline
02 — How Each Piece Works
Three Integration Points
Two are handled by us and can be implemented immediately on the current site. One requires the DataGrows backend.
Handled by us
Tracking Script + Forms
HubSpot's tracking script installs via GTM in minutes. The contact
and newsletter forms are replaced with HubSpot's JS embed —
not an iframe, it renders as native HTML in the
page and can be styled to match the site. Each submission creates
a contact in HubSpot automatically.
We also add one hidden field to the trial form and a GTM tag to populate it with the visitor's hutk cookie value. No change to how the form works — the field is invisible to the user.
↗ Tracking Code Docs
↗ Form Embed Docs
We also add one hidden field to the trial form and a GTM tag to populate it with the visitor's hutk cookie value. No change to how the form works — the field is invisible to the user.
Requires DataGrows backend
Backend → HubSpot API
When a user registers for a trial, the DataGrows backend creates
the account and then fires a
standard HTTP POST request to HubSpot's Contacts
API to create or update the contact in HubSpot — including the
hutk value from the form. The same pattern repeats for subsequent
events (subscription started, plan changed, cancelled).
HubSpot uses email as the deduplication key — so if the person already exists as a contact (from a form submission), the record is updated rather than duplicated. Authentication is via a HubSpot Private App token.
↗ Contacts API Docs
↗ Private Apps (Auth)
HubSpot uses email as the deduplication key — so if the person already exists as a contact (from a form submission), the record is updated rather than duplicated. Authentication is via a HubSpot Private App token.
Lives entirely in HubSpot
Lifecycle, Scoring, Workflows
Once data is flowing from both the frontend and the backend into
HubSpot, everything else — lifecycle stages, lead scoring, email
workflows, ad audiences — is configured entirely within HubSpot.
No further backend involvement is needed.
The richness of what we can automate in HubSpot is directly proportional to the events DataGrows can send. The minimum viable integration is trial registration + subscription status. Everything else adds precision on top.
↗ Lifecycle Stages
↗ Workflows
The richness of what we can automate in HubSpot is directly proportional to the events DataGrows can send. The minimum viable integration is trial registration + subscription status. Everything else adds precision on top.
03 — Why It Matters
Two Examples
Showing what becomes possible when the data flows correctly — and what breaks without it.
A: The full picture on a high-value trial
Accounting firm owner, 12 users, converts to paid on Day 6
1
Site + HubSpot
Clicks Google ad, browses for 3 minutes, leaves
HubSpot tracking script fires. Marco gets a hutk cookie. His
session — which ad, which pages, how long — is stored in
HubSpot anonymously. No form filled yet.
2
HubSpot Form
Returns the next day, fills the qualifier form
Contact is created in HubSpot. His anonymous session data
from yesterday merges with the new contact record via the
hutk. HubSpot now knows he came from a Google ad, visited
the pricing page twice, and identified himself as an
accounting firm owner.
3
Backend → HubSpot API
Registers for trial — backend fires API call to HubSpot
The trial form includes the hutk hidden field (populated by
GTM). The DataGrows backend creates Marco's account, then
immediately POSTs to HubSpot's Contacts API: contact updated
with plan type, trial dates, 12 users, and the hutk. HubSpot
moves him to Opportunity lifecycle stage
and enrolls him in the trial nurture workflow.
4
Backend → HubSpot API
Day 2: imports 45 clients and adds 3 team members
Two milestone events fire from the backend to HubSpot. His
lead score jumps — a 12-person firm that's actively setting
up the product on Day 2 is a strong signal. HubSpot's
workflow detects the score threshold and sends an internal
alert:
"High-value trial — 12 users, active on Day 2."
Sales rep follows up.
5
Backend → HubSpot API
Day 6: converts to paid — backend fires subscription event
The
subscription_started event fires. HubSpot
moves Marco to Customer lifecycle stage.
He's automatically removed from all acquisition ad
audiences, added to the customer success segment, and the
welcome email sequence kicks off. His complete journey —
from the first Google ad to paying customer — is fully
tracked and attributed.
B: What breaks without the backend integration
Same scenario — but the backend can't fire API calls
Without the backend API calls:
Marco's trial registration, his milestone activity, and his
eventual subscription are invisible to HubSpot. The contact record
stays as a form submission — no trial start, no engagement
signals, no conversion event. We can't move him through lifecycle
stages automatically, can't score his engagement, can't trigger
the sales alert on Day 2, and we have no way of knowing when he
converts (or churns). Every stage transition would require manual
CRM updates. The contact journey in HubSpot is incomplete — making
lead scoring, automated nurture, lifecycle workflows, and accurate
ad attribution all either broken or reliant on someone manually
maintaining the CRM.
The minimum we need from the DataGrows Dev Team to make this work: trial registration fires an API call, and subscription started/cancelled fires an API call. Everything else — milestones, engagement events — adds richness on top but isn't strictly required to get the system functioning.
The minimum we need from the DataGrows Dev Team to make this work: trial registration fires an API call, and subscription started/cancelled fires an API call. Everything else — milestones, engagement events — adds richness on top but isn't strictly required to get the system functioning.
04 — Roadmap
Action Items
Roughly sequenced. Phases 1 and 2 run in parallel — we set up HubSpot on the current site while the DataGrows Dev Team confirms and builds the backend integration. Everything after that builds on confirmed data flow.
Phase 1 — Confirm the plan (this week)
Both
DataGrows Dev Team reviews this data flow and confirms what's
technically feasible from the backend
Key questions: Can the backend make outbound HTTP POST
requests to HubSpot? Which events can be sent — at minimum,
trial registration and subscription changes?
Us
Create HubSpot Private App token and share with the DataGrows
Dev Team
Phase 2 — Set up HubSpot on current site (can start now, no new site
needed)
Us
Install HubSpot tracking script on current site via GTM
One Custom HTML tag, trigger: All Pages.
↗ GTM install guide
Us
Replace contact form and newsletter signup with HubSpot JS
embed
React component wrapping hbspt.forms.create() — not an iframe,
renders as native HTML. Create the forms in HubSpot first,
then embed using the Portal ID + Form GUID.
Us
Add hidden hutk field to trial registration form + GTM tag to
populate it
Hidden input:
name="hs_hutk". GTM Custom JS
variable reads the hubspotutk cookie. Custom HTML
tag populates the field on page load.
Us
Create custom contact properties in HubSpot for DataGrows data
Minimum needed: dg_plan_type, dg_trial_start_date,
dg_trial_end_date, dg_subscription_status, dg_user_count,
dg_account_id, dg_country.
↗ Custom properties guide
Phase 3 — Backend integration (DataGrows Dev Team)
DataGrows Dev
On trial registration: POST to HubSpot Contacts API to
create/update contact
Include: email, name, org, plan type, trial dates, user count,
country, and the hs_hutk value from the form payload.
↗ Contacts API
DataGrows Dev
On subscription started: fire event to HubSpot, update
subscription_status → "paid"
This is what moves the contact to Customer lifecycle stage and
triggers all downstream workflows. Non-negotiable for the
system to work.
DataGrows Dev
On subscription cancelled / trial expired: fire event to
HubSpot
Enables winback workflows and ad re-targeting. Include a
reason field if the platform captures cancellation reason.
DataGrows Dev
On key platform milestones: log timeline events to HubSpot
(nice to have — agreed set)
e.g. clients_imported, team_member_added, phase_1_complete. We
agree on the specific list based on what's achievable.
↗ Timeline Events API
Both
End-to-end test: trial registration → platform event →
subscription → HubSpot reflects correctly
Confirm contact is created, hutk matched, subscription status
updates, timeline events appear on the contact record in
HubSpot.
Phase 4 — Once data is flowing
Us
Finalise lead scoring and lifecycle stage framework based on
confirmed events
Us
Build lifecycle workflows — MQL, SQL, Trial, Customer,
Churn/Winback
Us
Import Mailchimp database and switch to HubSpot for all email
Us
Build ad audiences by lifecycle stage — connect Google Ads,
Meta, LinkedIn to HubSpot
Us
Begin new ads strategy development using audience data
Phase 5 — New site launch (minimal changes needed)
Us
Re-implement forms on Content Hub (native, no embed needed —
simpler than current)
HubSpot Content Hub has native form modules. The JS embed
approach used on the current site becomes even simpler on the
new site.
DataGrows Dev
Backend API calls remain unchanged — no modifications needed
on their side
The backend sends the same events to the same HubSpot
endpoints regardless of which site is live. The new site
doesn't affect the backend integration at all.
Us
Launch new ads plans using new site creative and refined
audience data
The key advantage: Because
we're setting up HubSpot on the current site now, by the time the new
Content Hub site launches the system is already proven and running.
The new site rollout is a continuity exercise, not a restart. All
contact history, scoring data, audiences, and workflow logic carry
over intact.
DataGrows × HubSpot — System Data Flow
Prepared for the DataGrows Dev Team · June 2026
Prepared for the DataGrows Dev Team · June 2026
Prepared by
