HubSpot Service Hub to SurveySparrow Ticket Migration Guide

HubSpot Service Hub to SurveySparrow Ticket Migration Guide

What This Migration Actually Involves

A HubSpot Service Hub to SurveySparrow Ticket Management migration extracts tickets, contacts, engagements (emails, notes, calls), attachments, and custom field data from HubSpot's CRM and loads them into SurveySparrow's ticket management module. You are moving from a full-featured CRM helpdesk to a purpose-built feedback-to-action ticketing layer — and the architectural gap between these two platforms is the core engineering challenge.

A note on naming: SurveySparrow's ticketing experience appears as Ticket Management in some docs and SparrowDesk in others (particularly pricing pages and Zapier integrations). Keep this in mind when searching their documentation.

Should You Make This Migration? A Decision Framework

Before committing engineering time, run through this decision tree:

Migrate if:

• Your primary support workflow is survey response → ticket → resolution, and you want that loop native rather than stitched together via Zapier
• You don't use HubSpot custom objects, deal-to-ticket associations, or multi-pipeline ticket routing
• Your team size is under 25 agents and HubSpot Service Hub Professional at $100/seat/month ($30,000/year for 25 seats) exceeds the value you extract from CRM-integrated support
• You are keeping HubSpot CRM for sales/marketing and only unbundling the support layer

Do not migrate if:

• You use HubSpot custom objects for ticket enrichment (e.g., linking tickets to product SKUs or subscription records)
• You rely on deal-to-ticket associations for sales-led support visibility
• Your workflows use multi-branch, cross-object conditional logic with delays and enrollment triggers
• You need a native knowledge base integrated with your helpdesk
• You need multi-pipeline ticketing with distinct SLA policies per pipeline stage
• Your reporting depends on HubSpot's cross-object reporting (e.g., tickets by deal stage, company revenue, or lifecycle stage)

Consider a hybrid approach if:

• You want SurveySparrow for feedback-driven ticket creation but still need HubSpot's CRM for account management — keep both, use the native integration for survey-to-CRM sync, and route only feedback-originated tickets through SurveySparrow

Why teams make this move

Teams migrate from HubSpot Service Hub to SurveySparrow for several practical reasons:

• Feedback-loop integration: SurveySparrow's core strength is connecting survey responses directly to tickets. Case management capabilities convert feedback into trackable tickets, and workflows automatically create tickets based on survey responses meeting specific criteria, such as low NPS scores.
• Cost reduction: HubSpot Service Hub Professional starts at $100/seat/month (as of 2024), with Enterprise at $150/seat/month. For a 15-agent team, that's $18,000–$27,000/year before add-ons. SurveySparrow's Business tier with Ticket Management starts significantly lower per seat, especially for teams that primarily need feedback-driven ticket workflows rather than a full CRM.
• Simplicity: Teams that don't use HubSpot's CRM capabilities (deals, pipelines, sequences) are paying for complexity they don't need. SurveySparrow has grown from a feedback tool into a complete ticketing solution with omnichannel support, AI-powered ticket categorization, and custom workflows.
• Stack unbundling: Some organizations keep HubSpot for CRM and marketing automation while moving daily support to a lighter service layer.

Core data model differences

The fundamental difference: HubSpot stores tickets as nodes in a relational CRM graph. SurveySparrow treats tickets as feedback-driven action items. You are moving from a complex relational model to a simpler, flatter structure — and that means data will be compressed, re-mapped, or lost.

Migration Approaches

Evaluating your migration method early dictates the timeline, cost, and data fidelity of the project.

1. Native CSV Export/Import

How it works: Export tickets and contacts from HubSpot as CSV files via the UI, transform them in a spreadsheet, then import contacts into SurveySparrow via its Contacts API or UI import and create tickets via the API.

Exporting HubSpot CRM data is straightforward: navigate to the specific CRM object you want to export, open the view containing the records, select the "All [object]" view, click "Export" in the top right corner, and choose your desired file format (CSV, XLSX, or XLS) and select which properties to include.

When to use it: Under 1,000 tickets, no engagement history needed, no attachments.

Pros: Zero engineering effort, good for proof-of-concept.

Cons: For XLS and XLSX files, there's a limit to the number of columns that can be exported (256 for XLS and 16,384 for XLSX). If your export contains more columns than the limit, the additional columns won't be included. CSV exports also do not include full engagement bodies (email threads, call logs, note content) — only ticket properties. SurveySparrow's public docs document CSV contact import, but ticket creation still requires the API.

Scalability: Small datasets only. | Complexity: Low.

2. API-Based Migration

How it works: Write custom scripts that call HubSpot's CRM API to extract tickets, contacts, engagements, and associations, transform the data, then POST to SurveySparrow's V3 Tickets API and Contacts API.

When to use it: 1K–100K+ tickets, full engagement history needed, custom fields require transformation, attachments must transfer.

Pros: Full control over data fidelity, handles engagement threads, preserves relationships, can be re-run for validation.

Cons: Requires engineering time (40–100+ hours). Must handle rate limiting on both sides. The CRM search API is capped at 4 requests per second across all search endpoints. That's not per endpoint — it's shared across contacts, deals, companies, and every other object type. If you're using search for deduplication checks during imports, this becomes your primary bottleneck.

Scalability: Enterprise-grade with proper batching. | Complexity: High.

3. Managed Migration Service

How it works: A specialist stages, maps, loads, validates, and owns rollback. Pre-built connectors for both platforms handle the ETL pipeline and edge cases.

Do not confuse SurveySparrow's documented HubSpot integration with a migration utility — the first-party docs focus on survey triggers, response mapping into HubSpot, and HubSpot contact import into SurveySparrow, not historical ticket migration.

When to use it: Limited engineering bandwidth, data is complex, timeline is tight, or you need zero-downtime cutover.

Pros: Fastest time-to-completion, expert handling of edge cases (duplicates, broken associations, attachment format conversion), built-in validation.

Cons: External cost (typically $2,000–$15,000+ depending on volume and complexity), requires sharing API credentials.

Scalability: Any size. | Complexity: Low (for you).

4. Custom ETL Pipeline

How it works: Route HubSpot data into a staging database or data warehouse (e.g., Snowflake, BigQuery) using tools like Fivetran, Airbyte, or Stitch, transform it via dbt or custom scripts, then load into SurveySparrow.

When to use it: You already have this infrastructure in place, have ongoing sync requirements, or need to combine HubSpot data with other sources during migration.

Pros: Highly resilient and auditable, supports incremental loads, reusable infrastructure.

Cons: Highest engineering effort. Overkill for a standard one-time helpdesk migration. Introduces unnecessary latency if you don't already have the infra.

Scalability: Enterprise-grade. | Complexity: Very High.

5. Middleware/iPaaS (Zapier, Make, Workato, n8n)

How it works: Use Zapier, Make, Workato, Tray.io, or n8n to trigger on HubSpot ticket events and create corresponding SurveySparrow tickets. SparrowDesk's Zapier docs position it as an action app that can create tickets or contacts, not a trigger app. SurveySparrow's Zapier docs are centered on survey events.

When to use it: Post-cutover sync or small operational automations — not historical migration.

Pros: No code (for Zapier/Make), fast setup for forward-looking sync. Workato and Tray.io offer more robust error handling for enterprise contexts.

Cons: Cannot migrate historical data (triggers only fire on new events). Zapier's HubSpot trigger doesn't expose full engagement bodies. Moving 100,000 tickets via Zapier will trigger timeout errors, hit API limits, and cost thousands in task usage. n8n (self-hosted) avoids per-task costs but requires infrastructure management.

Scalability: Low (ongoing drip only). | Complexity: Medium.

Comparison Table

Scenario Recommendations

• Small team, < 5K tickets, no custom objects: API script or CSV export. Budget 1–2 weeks of dev time for the API route.
• Enterprise, 50K+ tickets with engagement history: Managed migration service or custom ETL. Budget 3–6 weeks.
• Ongoing sync between platforms: iPaaS for new tickets + API script for historical backfill. Consider HubSpot webhooks (available on Professional+ tiers) for real-time change capture during the migration window rather than polling.
• Zero engineering bandwidth: Managed service — full stop.

Pre-Migration Planning

A successful migration is won in the planning phase. Never extract data before defining exactly what needs to move.

Data Audit Checklist

• Tickets: Total count, by pipeline, by status. Identify closed/archived tickets you may not need.
• Contacts: Total count, duplicates, contacts without tickets (skip these?).
• Companies: Count and associations. SurveySparrow has no Companies object — decide how to handle this data.
• Engagements: Count emails, notes, calls, tasks per ticket. This determines API call volume. For 50K tickets averaging 4 engagements each, budget ~200K+ API calls on the extraction side alone.
• Custom Properties: List all custom ticket and contact properties. Map each to a SurveySparrow field or decide to drop it.
• Attachments: Count and total size. SurveySparrow limits attachments to 15MB per file and supports only pdf, png, jpeg, mp3, csv, wav. Audit for .doc, .xlsx, .zip, .gif, and other unsupported formats — these need conversion or external storage.
• Workflows/Automations: These cannot be migrated. Document them for manual rebuild.
• Knowledge Base: SurveySparrow doesn't have a native KB — plan a separate destination (e.g., GitBook, Notion, Intercom Articles, or a standalone KB tool).
• Character encoding: If tickets contain non-Latin scripts (CJK, Arabic, Hebrew), emoji, or special characters, test a 50-ticket sample early to confirm SurveySparrow renders them correctly.
• Data residency: Identify which SurveySparrow data center your account uses. If your organization is subject to GDPR, CCPA, or other data residency requirements, confirm that the staging layer (your local database or cloud instance) and SurveySparrow's data center are in compliant regions. SurveySparrow support can confirm your data center location.

Prune Before You Migrate

Identify unused pipelines, closed tickets older than five years, and bounced contacts. Do not migrate technical debt. Mark each HubSpot object category as migrate, flatten, archive, or leave in HubSpot.

Define Migration Scope

• Time window: How many years of ticket history do you need? Migrating 5+ years of closed tickets adds cost without value for most teams.
• Active vs. archived: Consider migrating only open/pending tickets live, and archiving closed tickets as a CSV backup.
• Users/agents: Map HubSpot owners to SurveySparrow agents. Create agents in SurveySparrow first.

Migration Strategy

Risk Mitigation

• Always run a test migration with a 5–10% sample before full migration.
• Keep HubSpot in read-only mode during final cutover (don't delete data).
• Document your rollback strategy. If the migration fails validation, how quickly can you revert agents back to HubSpot?
• Maintain HubSpot active for at least 30 days post-migration.
• Document every field mapping decision for audit purposes.
• Data processing: If using a staging database, ensure it meets your organization's data handling policies. PII (customer emails, phone numbers, ticket content) will pass through the staging layer — encrypt at rest and delete staging data after successful validation.

Data Model and Object Mapping

Getting the mapping wrong means corrupted data that's expensive to fix. This section determines migration success or failure.

Object-Level Mapping

Field-Level Mapping

Handling Relationships and Dependencies

HubSpot's association model links tickets to contacts, companies, deals, and other tickets. SurveySparrow supports only requester_id (linking a ticket to a contact) and parent_ticket_id/child_ticket_ids for ticket hierarchy.

Migration order matters:

1. Contacts first — create all contacts in SurveySparrow, capture the returned IDs.
2. Map contact IDs — build a HubSpot Contact ID → SurveySparrow Contact ID lookup table.
3. Tickets second — create tickets with requester_id set to the mapped SurveySparrow contact ID.
4. Comments third — add engagement history as ticket comments after ticket creation, in chronological order.
5. Attachments last — upload attachments to their parent tickets.

Migration Architecture

Data Flow

HubSpot CRM API ──extract──▶ Staging Layer ──transform──▶ SurveySparrow V3 API
  │                            │                            │
  ├─ GET /crm/v3/objects/      ├─ Field mapping             ├─ POST /v3/contacts
  │   tickets                  ├─ ID remapping               ├─ POST /v3/tickets
  ├─ GET /crm/v3/objects/      ├─ Status/priority            ├─ POST /v3/tickets/batch
  │   contacts                 │   translation               ├─ POST /v3/ticket-comments
  ├─ GET /engagements/v1/      ├─ Engagement → comment       │
  │   engagements              │   conversion                │
  └─ GET /crm/v3/associations  ├─ Deduplication              │
                               ├─ HTML sanitization          │
                               └─ Validation                 │

HubSpot API: Extraction Pattern

The extraction phase is the primary bottleneck. HubSpot's API design requires a "chatty" extraction pattern to get a full ticket with its conversation history.

To get a complete ticket, your pipeline must:

1. GET /crm/v3/objects/tickets — returns basic ticket properties, paginated at 100 records max per page.
2. GET /crm/v3/objects/tickets/{ticketId}/associations/emails — returns IDs of associated emails.
3. POST /crm/v3/objects/emails/batch/read — fetches the actual email bodies using the IDs (up to 100 IDs per batch call).

Alternatively, the legacy Engagements API (GET /engagements/v1/engagements/associated/TICKET/{ticketId}/paged) returns all engagement types for a ticket in one call but is deprecated and may be removed.

This means migrating 100,000 tickets with an average of 4 replies each requires hundreds of thousands of API calls. You must implement robust batching, pagination (using HubSpot's after cursor), and exponential backoff to handle 429 Too Many Requests errors.

HubSpot rate limits: For privately distributed apps, the burst limit applies individually per app. The daily limit is shared across all apps within the same HubSpot account. Expect 100–150 requests per 10 seconds depending on your HubSpot tier. The CRM search API is significantly more constrained at 4 requests per second, shared across all object types.

Throughput benchmarks: Based on these rate limits, expect approximately 500–800 fully-hydrated tickets per minute (ticket properties + engagements) during extraction from HubSpot. For 100K tickets with engagement history, plan for 4–8 hours of extraction time alone, not counting transformation and load.

For bulk extraction, HubSpot's Exports API can help but is limited to one export at a time and 30 exports in a rolling 24-hour window.

SurveySparrow API: Capabilities and Constraints

• Create ticket: POST /v3/tickets — accepts subject (required, ≤ 200 chars), description, priority (required), status (required), assignee_id, team_id, custom_fields, attachments.
• Batch creation: POST /v3/tickets/batch — create multiple tickets in one call. Use GET /v3/tickets/batch/status/{token} to check completion status.
• Contacts: POST /v3/contacts for creation, GET /v3/contacts for lookup.
• Ticket Comments: Separate endpoint (POST /v3/tickets/{ticket_id}/comments) for adding comments post-creation.
• Authentication: SurveySparrow uses OAuth 2.0 for authentication. There are 2 ways you can authorize your app to connect with SurveySparrow — via Settings → Apps & Integrations.
• Data centers: Based on your account's data center, use the corresponding URL to call APIs. Reach out to support to know about your data center.
• Attachment limits: Max 15MB per file. Allowed formats: pdf, png, jpeg, mp3, csv, wav. HubSpot attachments in .doc, .xlsx, .gif, or .zip formats need conversion (e.g., LibreOffice CLI for .doc→pdf) or separate storage with a link in the ticket description.
• Rate limits: Not publicly documented in detail — higher tiers offer custom API limits. Start with conservative batch sizes (10–20 tickets per batch call), monitor for 429 responses, and increase gradually. In testing, lower-tier accounts may throttle at roughly 30–60 requests per minute, but verify against your own plan.

SurveySparrow ticket fields expose an internal_name for API use. Write your transforms against the field code (internal_name), not the display label — labels can be changed by admins without affecting the API contract.

Sample response from POST /v3/tickets:

{
  "data": {
    "id": 12345,
    "subject": "Billing inquiry - order #4821",
    "description": "Customer reports incorrect charge...",
    "priority": 2,
    "status": 1,
    "requester_id": 6789,
    "assignee_id": 42,
    "custom_fields": {
      "hubspot_original_id": "98765",
      "hubspot_created_date": "2024-01-15T09:30:00Z"
    },
    "created_at": "2024-06-20T14:22:01Z",
    "updated_at": "2024-06-20T14:22:01Z"
  }
}

Note that created_at reflects the API call timestamp, not the original HubSpot creation date — confirming the override limitation described above.

Step-by-Step Migration Process

Step 1: Extract Data from HubSpot

Extract to a local staging environment (a secure Postgres database or structured JSON files) before attempting any transformation. This decouples the extraction rate limits from the load phase.

import requests
import time
 
HUBSPOT_TOKEN = "your-hubspot-private-app-token"
BASE_URL = "https://api.hubapi.com"
headers = {"Authorization": f"Bearer {HUBSPOT_TOKEN}"}
 
def extract_tickets(after=None):
    """Extract all tickets with pagination."""
    tickets = []
    params = {
        "limit": 100,
        "properties": "subject,content,hs_pipeline,hs_pipeline_stage,hs_ticket_priority,hubspot_owner_id,createdate"
    }
    if after:
        params["after"] = after
 
    response = requests.get(
        f"{BASE_URL}/crm/v3/objects/tickets", headers=headers, params=params
    )
 
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return extract_tickets(after=after)
 
    response.raise_for_status()
    data = response.json()
    tickets.extend(data.get("results", []))
 
    next_page = data.get("paging", {}).get("next", {}).get("after")
    if next_page:
        time.sleep(0.15)  # Respect rate limits (~6-7 req/s)
        tickets.extend(extract_tickets(after=next_page))
    return tickets
 
def extract_engagements_for_ticket(ticket_id):
    """Get all engagements (emails, notes, calls) for a ticket."""
    resp = requests.get(
        f"{BASE_URL}/engagements/v1/engagements/associated/TICKET/{ticket_id}/paged",
        headers=headers,
        params={"limit": 100}
    )
    resp.raise_for_status()
    return resp.json().get("results", [])

Clean the HTML bodies of HubSpot emails during this phase. HubSpot often includes heavy tracking pixels (<img> tags with track.hubspot.com URLs) and inline CSS that render poorly in SurveySparrow's comment UI. Use a library like bleach or beautifulsoup4 to strip tracking elements while preserving readable formatting.

Step 2: Transform Data

# Priority mapping: HubSpot → SurveySparrow
PRIORITY_MAP = {
    "LOW": 1,
    "MEDIUM": 2,
    "HIGH": 3,
    "URGENT": 4  # Verify these IDs in your SurveySparrow instance via GET /v3/tickets/priorities
}
 
# Status mapping: HubSpot pipeline stage → SurveySparrow status
STATUS_MAP = {
    "1": 1,   # "New" → Open
    "2": 2,   # "Waiting" → Pending
    "3": 3,   # "Closed" → Resolved
    # Map each hs_pipeline_stage ID to a SurveySparrow status ID
}
 
def transform_ticket(hs_ticket, contact_id_map):
    """Transform a HubSpot ticket into SurveySparrow format."""
    props = hs_ticket.get("properties", {})
    subject = (props.get("subject") or f"[No Subject] - Ticket #{hs_ticket['id']}")[:200]
 
    return {
        "subject": subject,
        "description": props.get("content", ""),
        "priority": PRIORITY_MAP.get(props.get("hs_ticket_priority"), 2),
        "status": STATUS_MAP.get(props.get("hs_pipeline_stage"), 1),
        "requester_id": contact_id_map.get(hs_ticket.get("associated_contact_id")),
        "custom_fields": {
            "hubspot_original_id": hs_ticket["id"],
            "hubspot_created_date": props.get("createdate")
        }
    }

Key transformation rules:

• Truncate subjects to 200 characters (SurveySparrow limit).
• Set a fallback subject for tickets without one — SurveySparrow requires the subject field.
• De-duplicate contacts by email before import. HubSpot allows multiple contacts with the same email on free/Starter tiers; SurveySparrow may enforce uniqueness. Merge by email, keeping the most recently updated record.
• Normalize enum values through explicit lookup tables for statuses, priorities, and owners.
• Pre-create SurveySparrow custom ticket fields (via the API or admin UI) before the first load — the load will fail if referenced custom fields don't exist.
• Handle character encoding: ensure UTF-8 throughout. If HubSpot tickets contain emoji or non-Latin scripts, test rendering in SurveySparrow with a small sample first.

Step 3: Load into SurveySparrow

Always load Contacts first. SurveySparrow needs the Contact ID to associate incoming tickets.

SS_TOKEN = "your-surveysparrow-access-token"
SS_BASE = "https://api.surveysparrow.com"  # Use your data center URL
ss_headers = {
    "Authorization": f"Bearer {SS_TOKEN}",
    "Content-Type": "application/json"
}
 
def create_ss_contact(contact_data):
    """Create a contact in SurveySparrow."""
    resp = requests.post(f"{SS_BASE}/v3/contacts", headers=ss_headers, json=contact_data)
    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 10))
        time.sleep(retry_after)
        return create_ss_contact(contact_data)
    resp.raise_for_status()
    return resp.json()["data"]["id"]
 
def create_ss_ticket(ticket_data):
    """Create a ticket in SurveySparrow."""
    resp = requests.post(f"{SS_BASE}/v3/tickets", headers=ss_headers, json=ticket_data)
    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 10))
        time.sleep(retry_after)
        return create_ss_ticket(ticket_data)
    resp.raise_for_status()
    return resp.json()["data"]["id"]
 
def add_ticket_comment(ticket_id, comment_text):
    """Add a comment (from engagement) to a SurveySparrow ticket."""
    resp = requests.post(
        f"{SS_BASE}/v3/tickets/{ticket_id}/comments",
        headers=ss_headers,
        json={"content": comment_text}
    )
    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 10))
        time.sleep(retry_after)
        return add_ticket_comment(ticket_id, comment_text)
    resp.raise_for_status()

Store the mapping of HubSpot_Contact_ID → SurveySparrow_Contact_ID in your staging database. You need it for ticket association, rollback, and delta syncs.

Step 4: Load Tickets and Engagements

For each staged ticket:

1. Create the parent ticket in SurveySparrow using the batch or single endpoint.
2. Retrieve the new SurveySparrow_Ticket_ID.
3. Iterate through the associated HubSpot engagements in chronological order (sorted by hs_createdate ascending).
4. POST each engagement as a reply or internal note to the new ticket.

For parent/child ticket relationships, create parent tickets first, capture IDs, then create children with parent_ticket_id set.

Use batch creation (POST /v3/tickets/batch) wherever possible to reduce API calls on the SurveySparrow side. Batches of 10–20 tickets are a safe starting point; increase if no 429s are observed.

Step 5: Error Handling

import logging
 
logger = logging.getLogger("migration")
 
def safe_create_ticket(ticket_data, retry_count=3):
    for attempt in range(retry_count):
        try:
            return create_ss_ticket(ticket_data)
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                wait = (attempt + 1) * 10
                logger.warning(f"Rate limited. Waiting {wait}s...")
                time.sleep(wait)
            elif e.response.status_code >= 500:
                logger.error(f"Server error: {e.response.text}. Retrying...")
                time.sleep(5)
            else:
                logger.error(f"Failed to create ticket: {e.response.text}")
                logger.error(f"Payload: {ticket_data}")
                # Write to dead-letter queue for manual review
                write_to_dlq(ticket_data, e.response.text)
                return None
    logger.error(f"Exhausted retries for ticket: {ticket_data.get('subject')}")
    write_to_dlq(ticket_data, "max_retries_exceeded")
    return None

Log every API call, error, and skipped record. Route failures to a dead-letter queue (a JSON file or database table) for manual remediation. Log the full mapping for audit: {hubspot_ticket_id, surveysparrow_ticket_id, hubspot_contact_id, surveysparrow_contact_id, status, error_message}.

Recommended Module Structure

For teams building a custom migration, organize your code like this:

hubspot_to_surveysparrow/
├── config.py              # API tokens, base URLs, mapping tables
├── extract/
│   ├── contacts.py        # Paginated HubSpot contact extraction
│   ├── tickets.py         # Paginated ticket extraction with properties
│   ├── engagements.py     # Per-ticket engagement extraction
│   └── associations.py    # Ticket-contact association resolution
├── transform/
│   ├── field_mapper.py    # Property → field mapping with type conversion
│   ├── html_sanitizer.py  # Strip tracking pixels, normalize HTML
│   ├── deduplicator.py    # Contact dedup by email
│   └── validator.py       # Schema validation before load
├── load/
│   ├── contacts.py        # SS contact creation with ID capture
│   ├── tickets.py         # SS ticket creation (single + batch)
│   ├── comments.py        # Engagement → comment creation
│   └── attachments.py     # File download + format check + upload
├── validate/
│   ├── count_check.py     # Source vs target record counts
│   └── field_check.py     # Random sample field comparison
├── utils/
│   ├── rate_limiter.py    # Token bucket with backoff
│   ├── dlq.py             # Dead-letter queue for failed records
│   └── logger.py          # Structured logging for all operations
├── rollback/
│   └── cleanup.py         # Delete SurveySparrow records using stored ID mappings
└── main.py                # Orchestrator: extract → transform → load → validate

Use a token bucket rate limiter to stay under both HubSpot and SurveySparrow limits. Store the ID mapping table in SQLite or Postgres — you'll need it for relationship linking, rollback, and delta syncs. Run the validator after each load phase, not just at the end.

Edge Cases and Challenges

Inline Attachments and CDN Links

HubSpot emails often contain inline images (like signatures). If you migrate just the HTML, the image URLs will point to HubSpot's CDN (f.hubspotusercontent.com), which requires authentication to view. You must download the attachments and re-upload them to SurveySparrow natively. SurveySparrow only accepts pdf, png, jpeg, mp3, csv, wav at 15MB max. Filter out unsupported formats, convert .doc/.xlsx to PDF using a headless tool (LibreOffice CLI: libreoffice --headless --convert-to pdf input.docx), or skip with a logged warning. Files over 15MB must be split or archived externally (e.g., S3 with a presigned URL) with a link back from the ticket.

Duplicate Contacts

HubSpot allows multiple contacts with the same email (especially on free/Starter tiers). SurveySparrow may enforce unique emails. De-duplicate contacts before import — merge by email, keep the most recently updated record, and log the merged HubSpot contact IDs for audit.

Missing or Inconsistent Data

HubSpot tickets without a subject will fail SurveySparrow's required subject field. Set a fallback: " [No Subject] - Ticket #{hs_id}". HubSpot contacts without a valid email need a rule before load — SurveySparrow's contact import requires an email. Options: skip the contact (and assign the ticket to a generic requester), or generate a placeholder email (e.g., unknown+{hs_contact_id}@yourcompany.com).

Multi-threading and Chronological Order

Reconstructing conversation threads exactly as they appeared requires careful attention to the hs_createdate of every engagement. If pushed out of order, the ticket timeline becomes unreadable. Sort all engagements by hs_createdate ascending before posting as comments. If using batch ticket creation with multiple workers, process comments sequentially per ticket — do not parallelize comment creation within a single ticket.

Suspended or Deleted Users

If a ticket is owned by a HubSpot agent who is no longer with the company, SurveySparrow will reject the ticket creation if mapped to an invalid user ID. Map inactive users to a generic "Legacy Agent" account in SurveySparrow. Create this account before the migration begins.

Multi-Level Relationship Compression

HubSpot's Account → Contact → Ticket → Engagement chain has no direct equivalent in SurveySparrow. You'll flatten this to Contact → Ticket → Comments. Company data either becomes a custom contact property (e.g., custom_fields.company_name) or is dropped. Many-to-many associations (e.g., a ticket associated with 3 contacts) compress into a single requester — pick the primary contact and store additional contact emails in a custom field.

API Failures and Throttling

Burst limits are the ones that bite you. The daily caps are generous enough that most integrations won't hit them unless you're doing something wild. Implement exponential backoff with jitter (e.g., base_wait * 2^attempt + random(0, 1s)). Log every 429 response and track cumulative wait time — if it exceeds 30 minutes total in a single batch, your batch size is too aggressive. Reduce concurrency and retry.

Limitations and Constraints

What you will lose:

• Companies object: No way to represent company-level data natively. Must flatten to custom contact/ticket fields.
• Custom objects: Not supported at all.
• Multi-pipeline ticketing: SurveySparrow uses statuses and templates, not pipelines. If you have 4 pipelines in HubSpot, you'll need to re-model these as template types or status groups.
• Workflow complexity: SurveySparrow workflows trigger based on ticket creation, priority changes, status changes, and assignee changes. HubSpot's multi-branch, cross-object workflows with delays, conditional branches, and enrollment triggers are significantly more powerful.
• Knowledge Base: No native KB in SurveySparrow — migrate articles to a dedicated tool (GitBook, Notion, Intercom, etc.).
• Historical timestamps: The ticket creation API does not accept custom created_at values. Original dates must be stored in custom fields.
• Engagement richness: Email threads with headers, CC/BCC recipients, and inline images compress into flat text comments. Call recordings won't transfer. Meeting data is dropped.
• Deal-to-Ticket associations: If your team relies on HubSpot's Deal-to-Ticket linking for sales-led support, you lose that native visibility unless you build a custom integration.
• SLA granularity: The system includes internal notes for collaboration, status tracking through resolution, and SLA management for response times. SurveySparrow SLAs are simpler than HubSpot's SLA-per-pipeline-stage model.
• Cross-object reporting: HubSpot's ability to report on tickets by company revenue, deal stage, or contact lifecycle stage has no equivalent.

API constraints to plan around:

• SurveySparrow rate limits are plan-dependent and not publicly documented — start with conservative batch sizes and increase empirically.
• HubSpot extraction of 100K tickets with engagements takes 4–8 hours of API time alone due to burst limits (at ~500–800 tickets/minute with engagements).
• Always include the HubSpot Record ID in any export you might re-import later. It's the unique identifier HubSpot uses to match incoming rows to existing records. Without it, a re-import doesn't update your records; it duplicates them.
• If sales, renewals, or account structure still matter after go-live, keep a CRM system of record alongside SurveySparrow.

Validation and Testing

Record Count Comparison

Run this comparison after every test migration. A delta > 0 means records were dropped — cross-reference with error logs and the dead-letter queue.

Field-Level Validation

For a random 5% sample of migrated tickets (minimum 50 tickets):

• Compare subject, description, priority, status, assignee against HubSpot source.
• Verify the requester_id points to the correct contact.
• Confirm custom fields populated correctly (especially hubspot_original_id and hubspot_created_date).
• Check that engagement comments appear in chronological order.

Sample high-risk records specifically: oldest tickets, newest tickets, tickets with the most comments (10+), VIP customers, and tickets that should trigger workflows or SLAs.

User Acceptance Testing

1. Migrate 100 tickets as a pilot — include a mix of simple tickets and complex ones with 5+ engagements.
2. Have 2–3 senior support agents verify their tickets look correct in SurveySparrow.
3. Test workflows and automations built in SurveySparrow against the migrated data.
4. Run a full migration to a SurveySparrow sandbox (if available on your plan — confirm with SurveySparrow support, as sandbox availability varies by tier) before production.

Agents will catch formatting errors and missing context faster than any script.

Rollback Planning

Keep your HubSpot instance active and unchanged for at least 30 days post-migration. If SurveySparrow doesn't work out, you can revert without data loss. This is a one-way migration — SurveySparrow doesn't have a native export-to-HubSpot path.

Rollback procedure:

1. Re-enable HubSpot as the primary ticketing system for agents.
2. Use the stored ID mapping table to identify and delete migrated records from SurveySparrow (via DELETE /v3/tickets/{id} and DELETE /v3/contacts/{id}).
3. Any tickets created in SurveySparrow during the migration period must be manually re-entered in HubSpot or exported via SurveySparrow's API.

For rollback strategies, see how to roll back a failed migration after go-live.

Post-Migration Tasks

Rebuild Automations

HubSpot workflows do not export. You must manually recreate ticket automation logic in SurveySparrow:

• Auto-assignment rules → SurveySparrow ticket routing workflows.
• SLA policies → SurveySparrow SLA configuration (note: simpler model — one SLA set, not per-pipeline-stage).
• Escalation rules → SurveySparrow escalation workflows.
• Notification triggers → SurveySparrow email notification setup.

If you want a customer portal, publish ticket forms first — without published forms, customers cannot raise requests through the help center.

Treat workflow parity as its own workstream, not a checkbox. Budget 2–5 days depending on workflow complexity. Refer to our guide on migrating automations, macros, and workflows for a structured approach.

Update Email Routing

Update your DNS records and email forwarding rules if you are migrating support email addresses (e.g., support@company.com) from HubSpot's inbox to SurveySparrow's forwarding addresses. Test email receipt in SurveySparrow before deactivating HubSpot's inbox.

Run a Delta Migration

Execute a final sync to catch any tickets created or updated in HubSpot during the migration window. Use HubSpot's hs_lastmodifieddate filter to extract only records changed since the initial extraction timestamp. Alternatively, configure HubSpot webhooks (Professional+ tiers) to capture changes in real-time during the migration window. Freeze the last delta, validate, and only then redirect intake channels.

Train Your Team

SurveySparrow's UI is fundamentally different from HubSpot's. Budget 1–2 days for agent onboarding. Focus training on:

• Ticket creation from survey responses (the core workflow differentiator)
• Internal notes and collaboration
• SLA tracking and escalation visibility
• Workflow triggers and automation behavior
• Finding historical tickets using the hubspot_original_id custom field

Create a quick-reference mapping doc: "In HubSpot you did X, in SurveySparrow you do Y."

Monitor for Data Inconsistencies

For the first 2 weeks post-migration:

• Check for tickets with missing requesters (broken contact links).
• Monitor for duplicate tickets (search by hubspot_original_id to detect re-imports).
• Verify that new tickets created in SurveySparrow follow expected workflow patterns.
• Track routing, requester identity, and automation side effects for at least one full support cycle (typically 5–7 business days).

Best Practices

1. Back up everything first. Export a full HubSpot data dump (all objects, all properties) to CSV before starting. Store it where your team can access it for 12 months.
2. Never migrate directly to production. Always run a subset (e.g., 1,000 tickets) into a SurveySparrow test environment to validate your mapping logic. Run at least 2 test migrations with increasing data volume.
3. Freeze the schema. Implement a change freeze on HubSpot custom fields two weeks before the migration to prevent mapping drift.
4. Validate incrementally. Don't wait until the end to check data quality. Validate after each phase: contacts → tickets → comments.
5. Log everything. Every API call, every error, every skipped record. You'll need this for debugging and post-migration auditing.
6. Preserve HubSpot IDs. Store the original HubSpot ticket ID and contact ID as custom fields in SurveySparrow. This creates a traceable link back to source data and is essential for delta syncs and rollback.
7. Communicate downtime. While managed migrations can achieve zero downtime, DIY migrations usually require a cutover window. Notify your customers if response times will be delayed.
8. Handle PII with care. Ticket content and contact records contain personal data. Ensure your staging layer is encrypted, access-controlled, and purged after successful migration and validation.

For a full pre- and post-migration checklist, see our HubSpot Service Hub Migration Checklist. For post-migration QA, use our help desk data migration QA checklist.

Sample Data Mapping Table

Making the Right Call

Migrating from HubSpot Service Hub to SurveySparrow Ticket Management is a one-direction trade: you gain a tighter feedback-to-action loop and (typically) lower per-seat costs, but you lose CRM depth, custom objects, and workflow sophistication. That trade-off is worth it for teams whose primary workflow is survey → ticket → resolution and who don't depend on cross-object CRM reporting. It's the wrong move for teams that depend on the HubSpot CRM graph for cross-object reporting, deal-stage automation, or custom object enrichment.

The technical migration is straightforward in concept — extract, map, load — but the edge cases (engagement threads, attachment formats, rate limits, timestamp preservation, character encoding, duplicate contacts) add up fast. If your dataset is under 5K tickets with minimal customization, a weekend script project can handle it. Beyond that, the engineering time, risk, and validation burden make a strong case for a managed approach.

Whichever path you choose, validate early, validate often, and keep your HubSpot instance intact until you're confident.