A green import result is reassuring. It still leaves a business question: did the required information arrive in the right records, with the relationships your team needs?
We recommend reconciling an import against an approved expectation. That expectation should account for exclusions, existing records, repeated source rows and required relationships before you compare it with the result.
TLDR: Reconcile eligible source records to their destination identifiers, then validate required fields and associations separately. Explain every difference. Created-record counts alone are not enough because an import may also update existing records, and a record can arrive without a required relationship.
Write the expected result before importing
Define the source population, the extraction time and the changes permitted during the migration window. If the source continues changing, agree on a cutoff or a controlled follow-up method so the comparison has a stable meaning.
Then document how source rows become destination records. Identify excluded rows, rows that refer to the same entity, and records expected to update something already present in HubSpot.
HubSpot notes that the number of created or updated records can legitimately differ from the number of import rows. Its import-error documentation gives examples of that distinction. Your reconciliation should explain the difference for your data instead of assuming all counts must match.
The broader design work belongs in the migration scope. If that scope is still unclear, review HubSpot onboarding and training before treating reconciliation as a final administrative step.
Keep an identifier crosswalk
A crosswalk connects the approved source identifier to the destination record identifier and records the intended action. Use it to distinguish a missing record from a record that already existed and was updated.
HubSpot's import overview explains the unique identifiers used to recognize records and support updates and associations. Read the import-tool documentation when choosing the matching method.
Your working crosswalk should include the source key, destination key, expected action, observed result and any exception. Preserve the source values used for matching. If a row has no reliable key, resolve that issue or keep it in an approved exception queue.
Do not accept a name-only spot check as proof that every required record was represented. Use record-level evidence for the full included population, then add deeper checks for the cases that carry greater operational risk.
Work through a count example
Hypothetical example: An import source contains 120 rows. Your team approves 8 exclusions, leaving 112 eligible rows. Within those eligible rows, 12 rows represent 6 repeated pairs. Each pair should map to one retained contact, so the expected destination population is 106 distinct contacts.
The import creates 100 contacts and updates 6 existing contacts. Together, those results represent the expected 106 destination identifiers. The record-count reconciliation passes under these assumptions.
| Reconciliation item | Example count | Meaning |
|---|---|---|
| Source rows | 120 | Rows in the agreed source extract. |
| Approved exclusions | 8 | Rows deliberately outside the transfer. |
| Eligible rows | 112 | Source rows remaining after exclusions. |
| Repeated-row adjustment | 6 | Six pairs collapse from twelve rows to six entities. |
| Expected distinct contacts | 106 | Destination contacts required by the approved mapping. |
| Created plus updated contacts | 106 | One hundred created and six updated, matched by identifier. |
Now suppose all 106 contacts require a company relationship, but only 104 have the correct one. There are 2 unresolved relationship exceptions. The count check passes, but the migration is not ready for acceptance under the stated requirements.
These figures are invented for the calculation. They are not a benchmark, a platform limit or an observed client result.
Inspect the deliberate failures in the example
Here is a fictional excerpt from the same 106-contact result. The keys below are invented reconciliation references, not real HubSpot Record IDs. They show why the association check must remain separate from the count check.
- Contact C-001: Expected company A-01; observed company A-01. The relationship check passes.
- Contact C-002: Expected company A-02; observed company A-02. The relationship check passes.
- Contact C-105: Expected company A-05; no observed company. The relationship is missing and remains unresolved.
- Contact C-106: Expected company A-06; observed company A-99. A relationship exists, but it is the wrong one and remains unresolved.
Under the example's assumptions, all 106 contact identities are represented, but only 104 required relationships match. C-105 needs an approved association correction. C-106 needs the wrong relationship investigated before any replacement. Neither record should be silently removed from the required population to produce a passing result.
For each correction, retain the expected pair, the before-state, the approved action and the observed after-state. Recheck the affected pair and any other relationship that the correction could change. The result becomes accepted only when the stated requirements are satisfied or the accountable owner explicitly changes the scope.
Keep the arithmetic and the evidence in separate checks
The arithmetic for this example is 120 source rows minus 8 exclusions minus 6 repeated-row adjustments, giving 106 distinct contacts. The import result is 100 created plus 6 updated contacts. Both calculations produce 106, but the agreement between totals is only the start of the test.
Compare the expected and observed identifier sets. Record a missing expected identity, an unexpected extra identity and a conflicting identity separately. Then compare the required relationships and values. This sequence helps distinguish a wrong mapping from an approved consolidation, without assuming that every repeated source row is an error.
We recommend a reconciliation register with one row per expected entity and an additional record of each required relationship. Record the extraction time and mapping version. If either changes, preserve the earlier evidence and identify which checks must run again. Do not combine observations from different source snapshots into one unexplained total.
Frequently asked questions
Why can the import row count differ from the number of contacts?
First check the approved exclusions, repeated entities, expected updates and import errors. Explain the difference using identifiers and the actual import result instead of assuming every row creates a new contact.
Can a sample prove that every required record arrived?
A sample can examine selected values in depth, but it does not establish full population coverage. We recommend checking the identifier set for the complete included population and documenting what any deeper sample does and does not test.
What should remain open after the upload finishes?
Keep missing identities, incorrect relationships, rejected values and unresolved business decisions open with owners. The upload status can be complete while the acceptance status remains unresolved.
Validate relationships and important values
HubSpot documents an association-limit error in which record data is imported but the resulting records are not associated. The import-error guide supports treating relationship checks as a separate part of reconciliation.
For each required relationship, compare the expected source-to-destination pair with the observed pair. Also check values that drive important business behavior, such as ownership or an agreed status. Specify the allowed values and mapping rules rather than checking only whether a field is nonempty.
Your HubSpot portal audit checklist can help identify which downstream processes need attention. The acceptance test should focus on the dependencies affected by this import.
Give every exception a disposition
Use a small set of understandable outcomes: corrected and rechecked, accepted exclusion, awaiting a business decision, or unresolved failure. Record the reason, responsible role and next action.
Avoid repeatedly importing the same file without understanding the effect on existing records. Approve the correction method, retain the affected identifiers and reconcile the revised result. A second execution should add evidence, not make the original comparison impossible to reconstruct.
If an error suggests a wider configuration problem, investigate it separately. Our guide to common HubSpot issues provides additional context, but it does not replace the specific error details in your account.
Retain a concise acceptance pack
Keep the source definition, approved exclusions, mapping, identifier crosswalk, import results, reconciliation and unresolved exceptions together. Record who reviewed the result and what limitations they accepted.
We recommend that the business owner approve the outcome using that evidence. “Import completed” can remain the execution status; “accepted” should mean the agreed records, relationships and required values passed review.
For help defining those checks, review HubSpot operations and bring the source definition and expected result. The useful conversation starts before the final count appears.
Product documentation checked August 29, 2026. The worked example uses synthetic data and requires no changes to a live portal.
