HubSpot Data Sync Guide
Understand how data flows between your HubSpot portal and MarketingSoda Refine during the free database health scan.
Overview
This guide explains how data flows between your HubSpot portal and MarketingSoda Refine™ during the free database health scan, and what happens at each stage.
What Data Is Read
During the audit scan, MarketingSoda Refine reads the following contact properties from your HubSpot portal:
| HubSpot Property | What It Contains |
|---|---|
firstname | Contact's first name |
lastname | Contact's last name |
email | Contact's email address |
phone | Contact's phone number |
jobtitle | Contact's job title |
company | Contact's company name |
city | Contact's city |
state | Contact's state or region |
country | Contact's country |
createdate | When the contact was created in HubSpot |
lastmodifieddate | When the contact was last updated |
hs_linkedin_url | Contact's LinkedIn profile URL |
hs_seniority | Contact's seniority level |
department | Contact's department |
What Is NOT Read
- Deal or pipeline data
- Company records (separate from contact company field)
- Ticket or support data
- Marketing email engagement history
- Custom properties beyond the standard fields listed above
- Attachments, notes, or activities
How the Sync Works
The data sync is a one-time, one-direction read that happens during your scan:
Step 1: Authentication
When you click "Connect Your HubSpot," you authorize MarketingSoda Refine to read your contacts using HubSpot's OAuth protocol. This creates a temporary access token that is valid for approximately 30 minutes.
Step 2: Contact Fetching
MarketingSoda Refine reads contacts from the HubSpot CRM v3 API in pages of 100 contacts at a time, up to a maximum of 500 contacts (5 pages).
Step 3: Real-Time Scoring
As each page of contacts is fetched, the contacts are immediately sent to the scoring service. Contact data is processed in memory and is not written to disk or stored in a database.
Step 4: Report Generation
After all contacts are scored, the aggregate results are compiled into a report. Only aggregate statistics (averages, distributions, counts) are saved -- never individual contact data.
Step 5: Token Cleanup
After the scan completes (or fails), the HubSpot access token is cleared from the session. MarketingSoda Refine does not retain any persistent connection to your HubSpot portal.
What Data Is Stored
Stored (Aggregate Only)
| Data | Purpose | Retention |
|---|---|---|
| Overall composite score | Your health grade | 12 months |
| Per-dimension average scores | Dimension breakdown | 12 months |
| Grade distribution (A/B/C/D/F counts) | Distribution chart | 12 months |
| Top issues list | Issue cards | 12 months |
| Recommendations list | Action items | 12 months |
| Total contacts scanned (count) | Report header | 12 months |
| HubSpot portal ID | Report association | 12 months |
Never Stored
| Data | Reason |
|---|---|
| Individual contact names | Privacy -- not needed for aggregate scoring |
| Email addresses (of contacts) | Privacy -- only used during real-time scoring |
| Phone numbers | Privacy -- discarded after scoring |
| Any other contact PII | Only aggregate statistics are retained |
Lead Capture Data (Separate)
If you fill out the lead capture form to unlock your full report, the following information you provide is stored:
- Your first name and last name
- Your work email address
- Your company name
This is the information you enter, not data from your HubSpot contacts.
Sync Timing and Frequency
The Free Audit
The free audit is a one-time snapshot, not an ongoing sync. It reads your contacts once, scores them, and generates a report.
There is no continuous or scheduled sync with the free audit. Each time you want updated results, you must run a new scan.
Rate Limiting
- MarketingSoda Refine limit: One scan per IP address per minute.
- HubSpot API limits: MarketingSoda Refine respects HubSpot's rate limits (190 requests per 10 seconds). If rate limited, requests are automatically retried with appropriate delays.
Scan Duration
- Small portals (under 100 contacts): 1-2 minutes
- Medium portals (100-500 contacts): 2-5 minutes
- Maximum contacts per scan: 500
What Happens When the Sync Fails
During Contact Fetching
If the connection to HubSpot fails while reading contacts:
| Error | What Happens | What You See |
|---|---|---|
| Token expired (401) | The scan stops and you are prompted to reconnect. | "HubSpot authentication failed. Please reconnect." |
| Rate limited (429) | MarketingSoda Refine automatically waits and retries (up to 3 times). | The progress bar may pause briefly. |
| Network error | MarketingSoda Refine retries with exponential backoff (up to 3 attempts). | Progress may stall, then resume or show an error. |
| API error (5xx) | Retried automatically. If all retries fail, the scan stops. | "Something went wrong" with a "Try Again" button. |
During Scoring
If the scoring service encounters issues:
| Error | What Happens | What You See |
|---|---|---|
| Partial failure (under 50%) | Results are calculated from successfully scored contacts. | Your report may note a smaller sample size. |
| Majority failure (over 50%) | The scan fails entirely. | "Data quality scoring failed" with a "Try Again" button. |
| Service unreachable | Pre-flight check catches this before the scan starts. | "Scoring service is unreachable" error message. |
During Report Saving
If the report cannot be saved to the database:
| Error | What Happens | What You See |
|---|---|---|
| Database unavailable | Pre-flight check catches this before the scan starts. | "Database is not configured" error message. |
| Save failure | A generic error is shown. | "Something went wrong" with a "Try Again" button. |
How to Force a Re-Sync
Since the free audit is a one-time snapshot, "re-syncing" means running a new scan:
- Visit marketingsoda.ai/en/audit.
- Click "Connect Your HubSpot" to initiate a new OAuth connection.
- Approve access on the HubSpot authorization screen.
- Wait for the new scan to complete.
Each new scan produces a fresh, independent report. Previous reports are not overwritten.
When to Re-Scan
- After making significant changes to your HubSpot data (bulk import, cleanup, enrichment).
- Periodically (monthly or quarterly) to track improvement over time.
- When sharing results with stakeholders and you want current data.
Data Flow Diagram
Your HubSpot Portal MarketingSoda Refine
+-------------------+ +---------------------+
| | OAuth | |
| Contacts | ---------> | 1. Read contacts |
| (read-only) | (500 max) | (in memory) |
| | | |
+-------------------+ | 2. Score each |
| contact |
| (in memory) |
| |
| 3. Build aggregate |
| report |
| |
| 4. Store ONLY |
| aggregate stats |
| |
| 5. Clear token |
| from session |
+---------------------+
Individual contact data: NEVER stored
Access token: Cleared after scan
Report: Available for 12 months
Privacy and Security
Data in Transit
All communication between your browser, MarketingSoda Refine, and HubSpot uses HTTPS (TLS encryption).
Data at Rest
- Individual contact data is never written to any database or file.
- Aggregate report data is stored in an encrypted PostgreSQL database.
- HubSpot access tokens are stored in encrypted, httpOnly cookies with a 10-minute time-to-live.
Session Security
- OAuth state parameters are encrypted with AES-256-GCM to prevent cross-site request forgery (CSRF).
- Sessions automatically expire after 10 minutes.
- Tokens are cleared immediately after the scan completes.
Revoking Access
You can revoke MarketingSoda Refine's access at any time from your HubSpot settings: Settings > Integrations > Connected Apps > MarketingSoda DQ Audit > Uninstall
After the scan, MarketingSoda Refine does not retain any persistent connection. Revoking access is a precautionary step for your peace of mind.