Planhat to HubSpot Migration: The Technical Guide

A Planhat to HubSpot migration means translating a customer success data model into a CRM data model. These are different categories of software. Planhat tracks post-sale lifecycle — health scores, usage trends, renewal playbooks, NPS campaigns. HubSpot tracks pipeline, marketing attribution, and deal revenue. The overlap is real (both store companies and contacts), but the divergence is where every migration decision gets made.

The failure mode is predictable. Teams export everything, import it into contacts, companies, deals, and notes, and end up with a CRM full of flattened history that no one can report on, automate against, or trust. A good migration keeps HubSpot operational and keeps analytical history queryable somewhere else.

This guide covers the data model mismatch, Planhat's API and export surface, what HubSpot can absorb natively versus what requires Custom Objects or external storage, and — honestly — what you will lose in the move.

Why Teams Move from Planhat to HubSpot

Most Planhat-to-HubSpot migrations happen for one of three reasons:

• Platform consolidation. The company already runs HubSpot for marketing and sales and wants to eliminate a separate CS tool. One platform, one bill, one admin surface.
• HubSpot Service Hub adoption. Teams that bought Service Hub Enterprise expect it to cover customer success workflows that were previously in Planhat.
• Headcount or budget reduction. Planhat's per-seat pricing gets cut in favor of HubSpot seats the organization already owns.

None of these reasons eliminate the technical complexity. They just explain the business pressure behind it.

Planhat's Data Model: What You're Extracting

Planhat is a company-centric customer success platform where almost all data ultimately relates to the Company model. Understanding what lives in Planhat is the first step before you map anything to HubSpot.

Companies are at the center of Planhat's data structure — almost all data ultimately relates to the Company model, whether that's emails, assets, licenses, or usage metrics.

The core Planhat models you need to extract:

Planhat also stores Projects, Objectives, and Churn records, which may need extraction depending on your scope.

Beyond these structured models, Planhat stores three categories of data that have no direct HubSpot equivalent:

• Health Profiles — a score from 0–10 based on custom criteria, with the score's development over time tracked as Time Series data
• Time Series data — including Default/System Metrics, User Activities, Custom Metrics, and Calculated Metrics, tracked across Companies, End Users, Assets, and Projects
• Workflows (Playbooks) — automated series of steps (tasks and/or emails) that Planhat calls Workflows, previously known as Playbooks, with two types: Projects and Sequences

How Does the Planhat API Handle Data Extraction?

Planhat has a soft limit of 200 API calls per minute to its main API. The hard limit is 150 requests per second with bursts of up to 50 parallel requests. In practice, the soft limit is what you'll design around during extraction.

The API has a limit of 2,000 objects per request for most object types, while Companies are limited to 5,000 objects per request. Paginate with offset and limit query parameters. Loop through each endpoint until the response returns an empty array.

Authentication uses static API Access Tokens generated via Private Apps in Planhat Settings. Once a token is created, it appears once and lasts forever — store it securely.

Planhat also supports xlsx file import/export, where the file import corresponds to a bulkUpsert operation. Excel exports are useful for field discovery, spot checks, and UAT samples, but they flatten relational data — you lose conversation thread history, associative links between End Users and Assets, and historical NPS responses. For a full migration, the API is the only viable extraction path.

Key extraction constraints:

• Body size limit: There is a hard limit of 32MB on the body of each post to Planhat, relevant if you're writing back during reconciliation.
• Bulk upsert cap: For all bulk upsert operations, regardless of the model, there is an upper limit of 5,000 items per request.
• No export API for Workflows/Automations: Playbook templates, automation rules, and Health Profile configurations are not exposed via API endpoints. You must document them manually before decommissioning Planhat.
• Nested data in Conversations: Conversations and Notes often contain nested arrays for attachments or inline images. Parse these arrays, download the raw files, and host them temporarily so they can be uploaded to HubSpot's File Manager API.

Planhat to HubSpot Data Mapping

Every Planhat model needs a destination — HubSpot native object, HubSpot Custom Object, or external storage. This is the core decision matrix.

Direct mappings

These Planhat objects have clean equivalents in HubSpot:

Mappings that require Custom Objects (Enterprise-only)

HubSpot Custom Objects are Enterprise-only across every Hub. An Enterprise-level subscription allows for up to ten custom object definitions with up to 500,000 records each without additional charges. If you're not on Enterprise, these Planhat models have no clean home in HubSpot.

How should Conversations map from Planhat to HubSpot?

Map Planhat Conversations by type, not as a single notes dump. Planhat Conversations can represent email, chat, ticket, call, or manual note types. If you flatten everything to HubSpot Notes, you lose Conversation Types — Planhat's own integration documentation warns about this explicitly.

A workable pattern:

• Notes and internal account commentary → HubSpot Notes
• Phone-style interactions → HubSpot Calls (Call Types can be configured to preserve type fidelity)
• Support-ticket-style records that still need operational ownership → HubSpot Tickets
• Email history you need on the timeline → HubSpot Emails
• Full transcript archives, attachments, and thread-level fidelity → External archive or warehouse

Always include the original activity date when importing. If you omit it, HubSpot stamps the import time instead, which corrupts your timeline. Store the original Planhat conversation ID and type on the HubSpot record — even as a prefixed line in the note body or a custom property — to make validation and rollback possible.

Data that belongs in a warehouse, not HubSpot

Some Planhat data should not go into HubSpot at all. HubSpot is not a time-series database, and forcing this data in creates maintenance debt without analytical value.

• Time-series usage metrics. Planhat stores daily/weekly/monthly product usage data points per Company, End User, and Asset. HubSpot has no native time-series storage. Snapshot the latest value into a custom property (last_login_count, usage_score_current), but keep the historical trend line in BigQuery, Snowflake, or Redshift.
• Health Score history. Health Profiles calculate a score from 0–10 based on custom criteria, and the score's development over time is tracked as Time Series. Migrate the current health score as a custom Company property in HubSpot. Archive the full history to your warehouse.
• Calculated Metrics. Planhat computes derived metrics using formulas across objects. These calculations don't transfer — you'd need to rebuild them as HubSpot calculated properties (limited to basic arithmetic on the same object) or compute them externally.
• User Activity event streams. Raw event-level data (page views, feature clicks, API calls tracked per user) doesn't belong in a CRM. Export to your warehouse and reference it from HubSpot via an external URL property if needed.

The architecture for health scores specifically:

1. Extract historical time-series data from Planhat's /metrics and health endpoints.
2. Load into your warehouse (Snowflake, BigQuery, or Redshift) to preserve historical analytics.
3. Sync stateful values to HubSpot. Create custom properties on the HubSpot Company record: Current Health Score (Number), Health Trend (String: Up, Down, Flat), Last Active Date (Date).
4. Implement Reverse ETL. Use a tool like Census or Hightouch to query the warehouse daily and push the updated Current Health Score into HubSpot.

This keeps HubSpot fast and uncluttered while your CS team still has visibility into current customer health directly on the CRM record.

What Is Genuinely Lost in a Planhat to HubSpot Migration?

Be explicit with stakeholders about what cannot survive this move:

Health Score engine. Planhat's health scoring system is a configurable computation engine — it pulls from usage data, NPS, support tickets, login frequency, and custom metrics, weighted by rules your CS team defined. HubSpot has no equivalent. You can store the final score as a number property, but the live computation disappears. Rebuilding it requires either HubSpot Operations Hub calculated properties (far more limited), a custom integration that computes health externally and writes it back, or a third-party scoring tool.

Playbooks/Workflows as dynamic automation. Planhat Workflows adjust in response to data while running — groups of steps activate or deactivate as an End User carries out actions within your product. This is dynamic, data-driven sequencing tied to usage signals. HubSpot workflows operate on CRM property changes, not real-time product usage events. You must rebuild every playbook manually, and some will lose their trigger granularity.

Automations with health-score triggers. Planhat Automations work on an If this / Then that logic, for example, "If a Company Health Score climbs above 8 / Then create an Opportunity." Since the health score engine doesn't transfer, automations that depend on it break by definition.

Time-series trend visibility inside the platform. In Planhat, a CSM opens a company profile and sees a usage trend chart. In HubSpot, they'll see a current number in a custom property. The trendline is gone unless you build a dashboard link to an external BI tool or use HubSpot's CRM card extensions to display warehouse data inline.

NPS campaign machinery. Planhat's NPS Survey is wired into customer records, timelines, and workflows — every response can trigger follow-ups, owner changes, or health updates automatically. HubSpot's feedback surveys exist but are a different system with different trigger logic. Historical NPS records can be migrated as Custom Object records, but the campaign automation must be rebuilt.

Conversation type fidelity. If you map all Planhat Conversations to HubSpot Notes, the original type (email, chat, ticket, call) is lost. Planhat's own integration docs warn about this. Map by type to preserve fidelity.

Portal configurations. Planhat Portals let you share data views with customers as external users. HubSpot has no equivalent customer-facing portal for CS metrics.

Per-company person identity. If the same human exists in Planhat under multiple Companies as separate End User records, they may collapse into a single HubSpot Contact during deduplication, losing company-specific context.

Playbook execution history. Planhat tracks exactly when a playbook was triggered and which steps were completed. You can rebuild the automation logic in HubSpot Workflows, but the historical log of past executions cannot be migrated natively.

The goal is zero unplanned loss — not that everything must live inside HubSpot.

Step-by-Step Planhat to HubSpot Migration Process

Step 1: Audit and document Planhat configuration

Before writing any extraction code, document everything that lives in Planhat:

• Export the full list of custom fields across all models (Company, End User, Asset, etc.)
• Screenshot or manually record every Health Profile configuration — the factors, weights, and thresholds
• Document every Workflow (Playbook) template — triggers, steps, conditions, email templates
• List all Automation rules and their trigger conditions
• Record all NPS campaign configurations
• Map parent-child Company hierarchies

None of this configuration is API-exportable. If you decommission Planhat before documenting it, you lose it permanently.

Step 2: Design your HubSpot target schema

Decide what goes where before you extract anything:

• Standard objects: Companies, Contacts, Deals, Notes, Tasks
• Custom Objects (if Enterprise): Assets, Licenses, NPS Responses, Feature Requests
• Custom properties: Current health score, latest NPS score, ARR, renewal date, usage snapshots on Company/Contact records
• Data warehouse: Time-series metrics, health score history, user activity streams, calculated metric history

Create all Custom Objects, custom properties, and association definitions in HubSpot before you begin loading data. HubSpot schema changes after data is loaded are painful — property types can't be changed once records exist.

Create legacy ID fields on every target object. A planhat_id custom property on Companies, Contacts, and each Custom Object makes ID mapping, validation, and rollback dramatically easier.

Step 3: Resolve duplicate End User identities

Query Planhat End Users for cases where the same email appears across multiple companies. Decide your identity rule:

• Merge into one HubSpot Contact with multi-company associations
• Keep the most recent End User record and archive others
• Flag for manual review

This must happen before loading Contacts, not after.

Step 4: Extract data from Planhat via API

Write extraction scripts that paginate through each model:

import requests
import time
 
BASE_URL = "https://api.planhat.com"
HEADERS = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
 
def extract_all(endpoint, limit=2000):
    results = []
    offset = 0
    while True:
        resp = requests.get(
            f"{BASE_URL}/{endpoint}?limit={limit}&offset={offset}",
            headers=HEADERS
        )
        resp.raise_for_status()
        batch = resp.json()
        if not batch:
            break
        results.extend(batch)
        offset += limit
        time.sleep(0.35)  # Stay under 200 calls/minute
    return results
 
companies = extract_all("companies", limit=5000)
endusers = extract_all("endusers")
assets = extract_all("assets")
nps_records = extract_all("nps?npsExpiryDay=3650", limit=10000)

Extract in referential order: Companies → End Users → Assets → Licenses → NPS → Conversations → Notes → Tasks → Opportunities → Issues.

Step 5: Transform and map IDs

Build a mapping table that links Planhat _id values to HubSpot record IDs as you create records. Every association in HubSpot requires both record IDs, so you must maintain this lookup throughout the migration.

Key transformations:

• Planhat orgPath → HubSpot parent company association
• Planhat cId (company ID) on End Users → HubSpot Contact-to-Company association
• Planhat health score (current value) → HubSpot custom number property on Company
• Planhat NPS score + scoreType + comment → HubSpot Custom Object record with association to Contact and Company
• Planhat Conversation type → appropriate HubSpot engagement type (Note, Call, Email, or Ticket)

Step 6: Load into HubSpot

For HubSpot Enterprise accounts, the daily API limit is 1 million requests per day with a burst limit of 190 requests per 10 seconds. Use HubSpot's batch create endpoints (up to 100 records per batch call) to maximize throughput. Do not create records one by one — creating 50,000 Contacts individually will take hours and risk API throttling.

Load in this order:

1. Companies (with custom properties including current health score, ARR, planhat_id)
2. Contacts (End Users, with email as dedup key)
3. Company-to-Contact associations (using the Associations v4 API)
4. Deals (from Opportunities)
5. Custom Objects: Assets, Licenses, NPS Responses
6. Custom Object associations
7. Engagements: Notes, Tasks, Calls, Emails
8. Engagement associations

When linking Custom Objects to standard objects using the Associations v4 API, you must query HubSpot for the correct Association Definition IDs:

{
  "inputs": [
    {
      "from": {
        "id": "105234"
      },
      "to": {
        "id": "882910"
      },
      "type": "custom_object_to_company"
    }
  ]
}

Step 7: Archive time-series data to your warehouse

Extract time-series data from Planhat's metrics endpoints and load it into BigQuery, Snowflake, or Redshift. A practical schema:

CREATE TABLE planhat_health_scores (
    company_external_id VARCHAR,
    hubspot_company_id BIGINT,
    score DECIMAL(3,1),
    recorded_date DATE,
    profile_name VARCHAR
);
 
CREATE TABLE planhat_usage_metrics (
    entity_type VARCHAR,  -- 'company', 'enduser', 'asset'
    entity_external_id VARCHAR,
    metric_name VARCHAR,
    metric_value DECIMAL,
    period_start DATE,
    period_end DATE
);

Link warehouse records to HubSpot via hubspot_company_id or external ID. Surface the data in HubSpot by adding a custom property with a dashboard URL, or use HubSpot's CRM card extensions to display warehouse data inline. Configure your reverse ETL pipeline (Census, Hightouch, or similar) to sync the Current Health Score to HubSpot Company records on a daily cadence.

Step 8: Rebuild Workflows and Automations in HubSpot

Using your documentation from Step 1, rebuild each Planhat Workflow as a HubSpot workflow. Expect these limitations:

• HubSpot workflows trigger on property changes, form submissions, or date-based conditions — not on real-time usage event streams
• Multi-step sequences with conditional branching exist in HubSpot but use a different logic model
• Workflows that triggered on health score changes now require an external process to update the health score property, which then triggers the HubSpot workflow

Step 9: Validate

Run record-count reconciliation for every object type. Spot-check 5–10% of records manually, focusing on:

• Company hierarchy (parent-child) integrity
• Contact-to-Company associations
• Custom Object associations (Assets to Companies, NPS to Contacts)
• NPS score values and dates
• Note/Task content and timestamps
• Latest health snapshot and last-NPS values compared to Planhat source

For validation patterns and checklists, see our data migration mapping cheat sheet and CRM migration checklist. For building a structured validation process, see How to Build a Data Migration Playbook.

How Long Does a Planhat to HubSpot Migration Take?

The extraction itself is fast — Planhat's API is well-structured and generous on rate limits. The time goes into schema design, Custom Object configuration, HubSpot workflow rebuilds, and validation.

HubSpot Tier Requirements for Planhat Data

Not all Planhat data can land in every HubSpot tier:

• HubSpot Professional: Companies, Contacts, Deals, Notes, Tasks, custom properties. No Custom Objects — Assets, NPS records, Licenses, and Issues cannot be stored as structured data. You'd have to flatten everything into custom properties on Company/Contact records, losing the relational structure.
• HubSpot Enterprise: If your business requires a relationship or process beyond the standard CRM objects, you can create and define a custom object. Enterprise is the minimum tier for a migration that preserves Planhat's asset/license/NPS structure. Budget accordingly.

HubSpot limits custom object associations to 500 per record, which is relevant for high-volume accounts with many Assets or NPS responses per Company.

When Not to Migrate Everything to HubSpot

Some teams would be better served by a hybrid approach:

• Keep Planhat read-only for historical reference while running HubSpot for new activity. This avoids the time-series migration entirely.
• Migrate core records to HubSpot, warehouse everything else. Companies, Contacts, and current-state snapshots go to HubSpot. All historical data goes to your warehouse.
• Use the existing Planhat–HubSpot integration. Planhat's native integration can sync virtually any Planhat object with any HubSpot object, bidirectionally — including custom fields and data types. If you're keeping Planhat temporarily, use the built-in sync to seed HubSpot before decommissioning. The native integration won't export time-series data, health score history, or NPS records into HubSpot, so plan API-based extraction for everything else.

The guiding principle: warehouse first, CRM second. Land the raw Planhat export in a warehouse or staging database before you build the HubSpot load. That gives you replayability, easier validation, and a way to preserve data that should never have lived in a CRM in the first place.

The worst outcome is cramming time-series data into HubSpot custom properties and losing the ability to query, chart, or trend it. Be intentional about what HubSpot is for in your new stack.

Making the Call

A Planhat to HubSpot migration is a model translation project, not a data copy. The records that map cleanly — Companies, Contacts, Deals, Notes — are straightforward. The value of the migration depends on the hard decisions: what to model as Custom Objects, what to warehouse, what to abandon, and what to rebuild from scratch.

Get the schema design right before you extract a single record. Document every Workflow and Automation before you lose access. And be explicit with your CS team about what they'll lose — health score trends in-platform, dynamic playbook triggers, NPS campaign automation — so they can plan workarounds before cutover, not after.