How Data Ingestion Studio Works

Overview

Data Ingestion Studio is built around a simple principle: prepare and review data before it reaches HubSpot. This guide explains the ideas behind every import so the individual steps make sense and the results are predictable.

Each import belongs to one portal

An import is a saved piece of work for a single HubSpot portal. It keeps the uploaded file, your preparation and mapping choices, the prepared files and any automated import run.

• Imports appear in the history of the portal they were created for.
• Everyone with access to that portal can see its imports. People without access to the portal cannot open them, even with a shared link.
• Switching the Current portal returns you to Home with a clean workspace. The new portal's defaults apply to your next upload.

Always confirm the portal name and ID before preparing or importing. The ID is the definitive destination.

The workflow stages

Every import follows the same stages. You can move back and forth between them before delivery.

1. Upload: Choose the file, worksheet, header row and the rows and columns to process.
2. Prepare: Profile each column and apply clean-ups such as trimming, replacements, case changes and filling blanks.
3. Map: Connect source columns to HubSpot company, contact and note properties.
4. Details: Choose outputs, import modes, lookups, matching, standardisation, notes and event details.
5. Review: Prepare the files, read validation messages, correct source rows and download the results.

When automated ingestion is available and selected, three more steps follow: Automation, Confirm and Progress.

Your original file never changes

The Studio does not edit the uploaded file. Every preparation choice is stored as an instruction and reapplied to the original upload each time the import is prepared.

• Clean-ups do not stack. Changing a replacement or case rule replaces the earlier instruction rather than applying it twice.
• Skipped rows and columns stay in the original file and can be included again.
• You can always download the original upload from the import history.

This makes imports repeatable and auditable. You can adjust a decision without starting again or worrying about damaging the source.

Preparing files is not the same as importing

The Studio separates read-only work from changes in HubSpot.

Read-only activities include:

• Reading the portal's property list, owners and account details.
• Looking up existing companies and contacts to find matches.
• Preparing, previewing and downloading files.

Actions that change HubSpot always need a separate, explicit confirmation:

• Confirming an automated import.
• Creating new HubSpot properties.
• Adding new options to an existing dropdown property.

If your team uses Prepare files only, nothing is written to HubSpot until someone imports the downloaded files through HubSpot's own import tool.

Defaults versus import choices

Portal settings provide the starting point for new imports. Each import then keeps its own copy of those choices.

• Changing an open import never changes the portal defaults.
• Saving new defaults does not change existing imports or previously prepared files.
• Reopening an import restores the choices it was saved with, not the latest defaults.

Some choices are always made per import and are never saved as defaults, including mappings, row cutoffs, row decisions, absolute fallback dates and full-name splitting.

Apply changes, then rerun

When you change a preparation, mapping or review choice after files have been prepared, the Studio hides the previous downloads until you apply the change. This prevents anyone from downloading files that no longer match the configuration.

Reruns are incremental. Only the rows affected by a change are reprocessed, and previous matching evidence is reused where it is still valid. Shared results, such as company resolution and final files, are rebuilt so that every row stays consistent.

AI assistance is optional

The Studio is rules-first. AI assistance is used only when it is enabled for your workspace and switched on for the import.

• AI header mapping sends only column names and the allowed HubSpot property names. Cell values are never sent.
• AI company matching sends only the company properties checked in your portal settings, plus the filtered evidence used to score candidates.
• If the AI provider fails, the Studio reports the failure. A failed lookup is never treated as a confirmed "no match".

Check your organisation's data-sharing policies before enabling AI assistance.

Current boundaries

• The Studio works from CSV and XLSX files. It does not yet pull data directly from other systems' APIs or run on a schedule.
• It prepares companies, contacts, notes, marketing-event participation and contact custom-event files. Other HubSpot objects are not currently supported.
• Contacts are matched by exact email address or record ID, never by name alone.
• Custom-event occurrences are prepared as files only.

Planned capabilities are described in Furball Roadmap: From Imports to Data Orchestration.

What to do next

• Follow Get Started with Data Ingestion Studio for your first import.
• Read Data Ingestion Studio Best Practices before running business-critical imports.