Skip to main content

Data Backups (CRM Records)

Data Backups allow you to export CRM records (contacts, companies, deals, tickets, and custom objects) from your HubSpot portal to CSV files on a schedule. This is separate from Metadata Backups, which export configuration and structure.

Metadata vs. Data
  • Metadata Backups — Export portal configuration (properties, workflows, forms, pipelines) to Git
  • Data Backups — Export CRM records (contacts, companies, deals) to CSV files

What Gets Backed Up?​

Data Backups export CRM records with all their properties:

Object TypeDescriptionExample Data
ContactsIndividual people in your CRMName, email, phone, lifecycle stage, custom properties
CompaniesOrganizations and businessesCompany name, domain, industry, annual revenue
DealsSales opportunitiesDeal name, amount, stage, close date, associated contacts
TicketsSupport ticketsTicket name, status, priority, description, owner
Custom ObjectsYour custom CRM objectsAny custom object you've created (e.g., Projects, Subscriptions)

Each backup includes:

  • ✅ All standard properties
  • ✅ All custom properties
  • ✅ System fields (ID, created date, updated date)
  • ❌ Associations (relationships between objects) — coming soon
  • ❌ Engagement history (emails, calls, meetings) — coming soon

Creating a Data Backup Schedule​

Step 1: Navigate to Data Backups​

  1. Go to Connections in the sidebar
  2. Select your HubSpot portal
  3. Click the Data Backups tab
  4. Click Schedule Data Backup

Step 2: Configure the Backup​

HubSpot Connection

  • Select the portal you want to back up
  • Cannot be changed after creation (delete and recreate if needed)

Object Types to Backup

  • Check the object types you want to export:
    • ☑ Contacts
    • ☑ Companies
    • ☑ Deals
    • ☑ Tickets
    • ☑ Custom Objects
  • You can select multiple types in a single backup schedule

Schedule

  • Manual — Run only when you click "Run Now"
  • Daily — Runs once per day at a fixed time (UTC)
  • Weekly — Runs once per week on a specific day and time (UTC)

Storage Destination

  • Currently: Cloud Storage (CSV files)
  • Coming soon: Amazon S3 support

Step 3: Save and Activate​

  1. Click Create Schedule
  2. The backup is created and activated automatically
  3. If you selected a schedule (daily/weekly), it will run automatically
  4. For manual backups, click Run Now to trigger the first backup

Running a Manual Backup​

You can trigger a backup at any time, regardless of the schedule:

  1. Go to Connections → Select portal → Data Backups tab
  2. Find the backup configuration
  3. Click Run Now
  4. The backup job is queued and will start within a few seconds
  5. Click View History to see the progress

Backup History​

Each backup run creates a job with detailed logs:

Viewing Backup History​

  1. Click View History on a backup card
  2. The history modal shows all past runs with:
    • Status — Pending, In Progress, Done, Failed
    • Started At — When the backup began
    • Completed At — When it finished
    • Logs — Detailed execution logs
    • Download Links — CSV files for each object type (valid for 7 days)

Backup Status​

StatusDescription
PendingJob is queued, waiting to start
In ProgressCurrently extracting and exporting data
DoneBackup completed successfully
FailedBackup encountered an error

Downloading Backup Files​

CSV File Structure​

Each object type is exported to a separate CSV file:

contacts.csv
companies.csv
deals.csv
tickets.csv
custom_objects.csv

CSV Format​

Each CSV file contains:

  • hs_object_id — HubSpot record ID
  • created_at — When the record was created
  • updated_at — When the record was last modified
  • All properties — One column per property (standard + custom)

Example contacts.csv:

hs_object_id,created_at,updated_at,firstname,lastname,email,phone,lifecyclestage,custom_property_1
12345,2024-01-15T10:30:00Z,2024-03-20T14:22:00Z,John,Doe,john@example.com,555-1234,customer,value1
67890,2024-02-10T09:15:00Z,2024-03-21T11:45:00Z,Jane,Smith,jane@example.com,555-5678,lead,value2

After a backup completes:

  1. Click View History on the backup card
  2. Find the completed run
  3. Click the Download button for each object type
  4. The CSV file downloads to your computer
Link Expiration

Download links are valid for 7 days after the backup completes. After that, you'll need to run a new backup.

Use Cases​

1. Disaster Recovery​

Scenario: Your HubSpot portal is accidentally corrupted or data is deleted.

Solution:

  • Schedule daily data backups
  • If data is lost, download the most recent CSV backup
  • Re-import the data using HubSpot's import tool or API

2. Data Archival & Compliance​

Scenario: You need to retain historical CRM data for compliance (GDPR, HIPAA, etc.).

Solution:

  • Schedule weekly data backups
  • Download and archive CSV files to your secure storage
  • Maintain a complete audit trail of CRM data over time

3. Data Migration​

Scenario: You're migrating from HubSpot to another CRM or consolidating portals.

Solution:

  • Run a manual data backup before migration
  • Download all CSV files
  • Use the CSVs to import data into the new system

4. Analytics & Reporting​

Scenario: You want to analyze CRM data in external tools (Excel, Tableau, Python).

Solution:

  • Schedule daily or weekly backups
  • Download CSV files
  • Import into your analytics tool for custom reporting

5. Data Auditing​

Scenario: You need to audit changes to CRM records over time.

Solution:

  • Schedule daily backups
  • Compare CSV files from different dates to identify changes
  • Track property value changes, new records, and deletions

Pausing and Resuming​

You can pause a backup schedule at any time:

  1. Go to the Data Backups tab
  2. Toggle the Active switch on the backup card
  3. Paused backups will not run on schedule
  4. Toggle again to resume
tip

Pausing a backup does not delete existing backup files. You can still download past backups while the schedule is paused.

Editing a Backup Schedule​

To change the schedule or object types:

  1. Click Edit on the backup card
  2. Modify the settings:
    • Object types (add or remove)
    • Schedule frequency
    • Active status
  3. Click Save Changes
note

You cannot change the HubSpot connection after creation. To back up a different portal, create a new backup schedule.

Deleting a Backup Schedule​

To delete a backup schedule:

  1. Click Delete on the backup card
  2. Confirm the deletion
  3. The schedule is removed, but existing backup files remain accessible until their download links expire (7 days)

Storage & Limits​

Storage Location​

Data backups are stored in secure cloud storage:

  • Files are encrypted at rest
  • Path structure: backups/{workspace}/{connection}/{date}/{object_type}.csv
  • Download links are signed URLs valid for 7 days

File Size Limits​

Object TypeTypical Size (per 10k records)Notes
Contacts~5-10 MBDepends on number of properties
Companies~3-8 MBFewer properties than contacts
Deals~4-9 MBIncludes deal-specific properties
Tickets~3-7 MBVaries by custom properties
Custom ObjectsVariesDepends on schema complexity
Large Portals

For portals with 100k+ records, backups may take 5-15 minutes to complete. The system uses streaming to handle large datasets efficiently.

Performance & Timing​

Backup Duration​

Portal SizeEstimated Time
< 10k records1-2 minutes
10k - 50k records2-5 minutes
50k - 100k records5-10 minutes
100k+ records10-20 minutes

Scheduling Best Practices​

  • Daily backups: Schedule during off-peak hours (e.g., 2:00 AM UTC)
  • Weekly backups: Choose a low-activity day (e.g., Sunday)
  • Manual backups: Run before major data imports or migrations

Troubleshooting​

Backup Stuck in "Pending"​

Cause: Background worker is overloaded or not running.

Solution:

  • Wait 5-10 minutes
  • If still pending after 15 minutes, contact support

Backup Failed with "API Rate Limit"​

Cause: HubSpot API rate limits were exceeded.

Solution:

  • Wait 1 hour and retry
  • Reduce the number of object types in the backup
  • Schedule backups during off-peak hours

Cause: Download links are only valid for 7 days.

Solution:

  • Run a new backup
  • Download the CSV files immediately after the backup completes
  • Archive files to your own storage for long-term retention

CSV File is Empty or Incomplete​

Cause:

  • No records exist for that object type
  • API permissions are insufficient
  • Backup was interrupted

Solution:

  • Check that records exist in HubSpot for that object type
  • Verify OAuth scopes include read access for the object type (e.g., crm.objects.contacts.read)
  • Retry the backup

Custom Objects Not Appearing​

Cause: Custom objects require specific OAuth scopes.

Solution:

  • Ensure your connection has crm.objects.custom.read scope
  • Reconnect the portal with the correct scopes
  • See OAuth Scopes for details

Security & Privacy​

Data Encryption​

  • In Transit: All data is encrypted using TLS 1.2+ during extraction from HubSpot
  • At Rest: CSV files are stored in encrypted cloud storage
  • Download Links: Signed URLs with 7-day expiration

Access Control​

  • Only workspace admins can create, edit, or delete data backup schedules
  • Both admins and members can view backup history and download files
  • See Permissions for details

PII Considerations​

Data backups contain Personally Identifiable Information (PII):

  • Contact names, emails, phone numbers
  • Company information
  • Custom properties that may contain sensitive data

Best Practices:

  • Download and store CSV files securely
  • Delete downloaded files after use
  • Use encrypted storage for archived backups
  • Follow your organization's data retention policies

Data Backups vs. Metadata Backups​

FeatureData BackupsMetadata Backups
What's Backed UpCRM records (contacts, deals, etc.)Portal configuration (properties, workflows, forms)
FormatCSV filesJSON/YAML in Git
StorageCloud Storage (or S3)GitHub repository
Use CaseDisaster recovery, data archival, analyticsVersion control, deployment, drift detection
RestorationManual re-import via HubSpot UI or APIAutomated deployment via HubSpot Deploy
FrequencyDaily, weekly, or manualHourly, daily, weekly
File SizeLarge (MB to GB)Small (KB to MB)
Use Both

For complete protection, use both data backups and metadata backups:

  • Metadata backups protect your portal's structure and configuration
  • Data backups protect your CRM records and customer data

FAQ​

Can I restore data directly from a backup?​

No. Data backups are exported as CSV files. To restore data, you must:

  1. Download the CSV file
  2. Use HubSpot's import tool or API to re-import the records

Automated restoration is planned for a future release.

Are associations (relationships) backed up?​

Not yet. Currently, only object properties are backed up. Association data (e.g., which contacts are associated with which deals) is planned for a future release.

Can I back up engagement history (emails, calls, meetings)?​

Not yet. Engagement history backup is planned for a future release.

How long are backup files stored?​

Download links expire after 7 days. After that, the files are deleted from storage. To retain backups long-term, download and archive them to your own storage.

Can I export to S3 instead of cloud storage?​

S3 support is coming soon. Currently, all data backups are stored in our secure cloud storage.

Do data backups count against my HubSpot API limits?​

Yes. Data backups use the HubSpot API to fetch records, which counts against your portal's API rate limits. Backups are designed to be efficient and stay within limits, but very large portals may experience temporary rate limiting.

Can I schedule backups for multiple portals?​

Yes. Create a separate backup schedule for each portal. Each schedule can have its own object types and frequency.