HubSpot multi-object imports: reconcile records and relationships

SOURCE-BASED ANALYSIS · NO HANDS-ON RATING

Count objects and relationships separately

HubSpot's multi-object importer supports creating or updating records and associating objects. Its file-format guide describes including identifiers for the related records in each row, or using a common column across two files. A repeated contact row can describe another relationship rather than another person. The result depends on identifiers and the selected import mode; do not infer identity from matching display names alone.

Our recommendation is a migration contract with two parts: the intended records and the intended links between them. A total of 20 spreadsheet rows does not establish how many contacts, companies and opportunities should exist afterward.

A fictional partnership pilot

Assume a pilot contains four people, three companies and two deals. One adviser works with two companies, and each deal involves two people. Write an expected object register with synthetic source references, then an association table listing each intended pair. Use example.com addresses and an isolated destination dataset.

For example, contact C1 should link to companies O1 and O2, while deal D1 should link to contacts C1 and C2. Those relationships are deliberate sample requirements, not HubSpot defaults. Decide separately which company relationship is primary and whether a label is needed.

Prepare the import

1. Choose which objects are being created, updated or only associated.
2. Select the documented identifier for each object and keep it consistent across rows.
3. Give columns unambiguous object-specific names before mapping.
4. Review the import mode for each object instead of assuming one global create rule.
5. Preview mappings and verify the intended association structure.
6. Run only the synthetic pilot and record the result for every source reference.

Inspect membership, not only totals

Our acceptance rule for the pilot is four intended contacts, three intended companies, two intended deals and exactly the declared relationships. If the headline totals match but C1 links to O3 instead of O2, the migration is still wrong. Inspect a record from both sides of the relationship.

Include a namesake, a missing identifier and an intentionally unmatched company reference in the pilot. Define which cases should be rejected or reviewed before creating live associations. The same source value must not mean a contact ID in one file and a company ID in another.

Reconcile errors without repeating the whole migration

Retain the source file, mapping version, selected modes and import result. If an association fails while records are created, separate the missing relationship from missing objects. Re-importing the whole file without understanding that distinction can create more work instead of repairing the link.

Our recommendation is to correct a small known subset and verify it before applying the same fix broadly. Document any automation that may run on created or updated records; a later data repair does not automatically reverse a message or other external side effect.

Launch gate

Proceed when a second reviewer can reconcile every source reference and relationship, explain intentional exclusions and identify a recovery procedure. Consult current account options for specialized associations and required properties. This is an editorial pilot procedure, not a completed import test, a migration guarantee or a claim about plan-specific limits.