A HubSpot import is successful only when it creates or updates the intended records, preserves important existing information, and associates each contact with the correct company. A file that uploads without errors can still fail those tests. Preparing the identity map and expected operations before import is more useful than trying to repair a large batch afterward.
This guide provides an original staging method, fictional field map, and reconciliation ledger for company and contact research. Platform-specific identifier and association guidance is checked against HubSpot's documentation. The examples are reviewed design specimens, not a claim that a live HubSpot portal was tested. Your portal's properties, permissions, automation, and subscription features still need a representative test before a full import.
What you’ll be able to do
- Keep company and contact identifiers in separate, clearly labeled columns.
- Preserve existing HubSpot Record IDs when enriching records already in the CRM.
- Decide whether each incoming field may update, fill a blank, remain research-only, or require review.
- Treat contact-company associations as explicit relationships that need their own checks.
- Reconcile creates, updates, holds, and associations before enabling downstream outreach.
Define whether the batch creates, updates, or associates
Write a batch purpose in plain language: create new companies and contacts, enrich existing companies, add contacts to existing accounts, or correct associations. A mixed file can support several operations, but each row should have an intended action. Otherwise an unexpected new record may be mistaken for a successful update.
Separate the raw source file from the prepared import file. Give both a batch identifier and record the export or receipt date. Retain the original column names and values in the raw copy so a reviewer can trace a change. The prepared copy should contain only fields that the operator intends to map, plus clearly identified review columns that will not be imported.
Before working on the file, identify the properties and workflows that an import could affect. A lifecycle change, owner update, or populated email property may interact with existing automation. The CRM administrator should review those consequences. The research supplier is not responsible for knowing every workflow configured in the customer's portal, so make the destination review an explicit part of the process.
Keep company facts and contact facts on the right object
Company facts describe the organization: name, canonical website, business model, product category, public technology observation, and company-level research. Contact facts describe the person: name, role, business email, contact source, and person-specific preferences. The relationship between them is an association, not merely a repeated company name in a text field.
Do not put a company score on every contact without deciding what that duplication means. If the score changes, several contact records may become inconsistent. Prefer a company-level field and a clear association unless the workflow has a specific reason to copy a derived value. Similarly, a contact's opt-out or conversation preference should not be hidden in a company research paragraph.
Long research belongs in a linked brief or a suitable narrative property with clear versioning. Sortable fields should remain concise and typed. A field such as research_fit_status can support filtering, while the brief explains the evidence and uncertainty. Keep the proposed field design small enough that the team can maintain it after the initial import.
Choose the unique identifier for each object
HubSpot's import guidance supports Record ID as an identifier for existing records, with Email available for contacts and Company domain name for companies. Multiple-object files need identifiers for each object. When both object types use Record IDs, clearly distinguish the headers, such as Record ID - Contacts and Record ID - Companies. Verify the actual mapping rather than relying on header similarity.
For existing records, export the native IDs with the fields you intend to enrich and preserve those IDs unchanged through the research process. A supplier's company key is useful for tracking the source, but it is not automatically a HubSpot Record ID. Keep the two identifiers in different columns and document their relationship.
For new records, choose and review the identifier according to the import design and current platform rules. A website domain is useful but can be ambiguous for subsidiaries, franchises, or multiple entities sharing a corporate site. A business email can change when a person changes employers. Put uncertain matches in a hold queue rather than forcing them into the most convenient existing record.
References: HubSpot: Format import files ↗
Build an explicit source-to-property map
Prepare a mapping sheet before opening the import screen. For every source column, list the object, destination property, data type, intended update behavior, and reviewer. Use a separate entry for fields that remain in the audit file only. This prevents an operator from mapping an unfamiliar column to the nearest available property during a time-pressured import.
Create necessary custom properties before the main batch and confirm their allowed values. A dropdown field needs consistent options; a date field needs a supported format; a numeric score needs an understood scale. Do not use a free-text field merely to avoid deciding what the values mean. A small data dictionary makes later filtering and reporting more reliable.
Protect fields that should not be replaced by public research, including customer-stated preferences, current ownership, active opportunity context, and internally verified information. If the incoming value conflicts with the CRM, create a review item. Do not assume the newest file contains the newest fact. The source date, observation date, and actual evidence determine whether an update is appropriate.
| Source column | Object and destination | Proposed handling |
|---|---|---|
| hubspot_company_id | Company Record ID | Preserve for reviewed updates |
| hubspot_contact_id | Contact Record ID | Preserve separately from company ID |
| canonical_domain | Company domain name | Review entity match before mapping |
| business_email | Contact Email | Review identity and existing preferences |
| research_fit_status | Company custom property | Use documented allowed values |
| research_observed_at | Company custom date property | Preserve the observation date |
| research_source_url | Company custom source property | Retain evidence for the finding |
| import_batch_id | Relevant custom batch property | Record the batch for reconciliation |
Normalize cautiously and retain the original value
Trim accidental whitespace and standardize predictable formatting, but retain the raw value in the audit file. Normalize domains to the agreed representation without treating a redirect as proof that two legal entities are identical. Preserve the original URL when it supplies evidence about the specific company page or business unit researched.
Handle names as text. Do not split a person's name into components using a rule that assumes every naming convention is identical. If the source already provides reviewed first and last names, preserve them. If it provides only a full name, decide whether the destination workflow can use it directly or whether manual review is needed.
Treat blank, unknown, not applicable, and not researched as distinct states in the staging file. A blank phone field should not become a made-up number or erase a valid existing value accidentally. The import configuration and property behavior determine what happens to blanks, so test the intended behavior on a representative record before the full batch.
Specify associations as relationships, not guesses
HubSpot documents one-file association imports using a unique identifier for each object on the same row. Two-file imports can use a common column to connect records. If one contact is associated with several companies, the relevant relationship needs explicit representation. Design the file around the actual association you intend to create and check any association-label requirements in the current documentation.
Prepare an association ledger with contact_key, company_key, relationship_type, source, and review_status. This ledger can reveal problems that are invisible in a flat list, such as one person attached to the wrong subsidiary or a repeated contact linked to several unrelated companies because of a copied domain.
Decide how to handle parent companies, subsidiaries, advisers, and contractors. A person's email domain may identify an employer while the research concerns a client they advise. Do not automatically equate that email domain with the target account. The relationship should be supported by the source and the campaign's purpose. Hold uncertain associations until a reviewer can explain them.
References: HubSpot: Format import files ↗
Worked example: two companies and three contacts
This fictional example contains two companies, Alder Labs and Beacon Services. Alder already exists in HubSpot with company ID 4101. One Alder contact exists with contact ID 8201, while a second contact is new. Beacon and its one contact are both new. The file also includes a research observation for each company. These invented identifiers are illustrative only.
The operator prepares one update for Alder, one new company for Beacon, one contact update, and two new contacts. The association ledger contains three intended contact-company relationships. The operator does not expect five new objects simply because the file has several rows. Repeated company information supports the associations but should not create repeated companies when identifiers are mapped correctly.
The mapping review checks that Alder's company ID goes to the company identifier and the existing person's contact ID goes to the contact identifier. The new contact has no fabricated CRM ID. Research fields map to the company object, and the contact's preference history remains protected. The ledger arithmetic is checked before import; the actual portal behavior still requires a controlled test.
After the test, the reviewer opens each company and contact record, confirms associations, and compares the relevant properties with the expected map. A contact appearing under the wrong company is a failed test even if the import summary reports no formatting error. The review records both object counts and relationship correctness.
Review downstream automation before the test
List workflows, lists, sequences, notifications, and assignment rules that may react to imported properties. Ask whether creating a contact, changing an owner, or populating a qualification field can trigger an action. The answer depends on the portal configuration, not merely the CSV format. Review the actual enrollment conditions with the administrator.
Use a staging or review status where the process supports it, and ensure that the status truly prevents unintended actions. A field named import_review does nothing by itself unless the relevant workflows honor it. Test the control with a representative record. Do not assume that disabling one workflow prevents all other systems from acting on the imported data.
Keep the test and production batches distinguishable through a batch property or another approved method. This helps identify records if correction is needed and lets the reviewer inspect only the affected cohort. Avoid relying on creation time alone when other imports or manual record changes occur in the same period.
Test the exceptions that could cause costly errors
Choose a test set that includes a new company, an existing company, a new contact at an existing company, an existing contact update, a missing optional value, a repeated company with two contacts, an uncertain domain, and a suppressed contact. The goal is not statistical sampling; it is coverage of important behaviors.
Write expected results before running the test. For each row, note the intended object action, protected fields, associations, and downstream behavior. An existing owner should remain unchanged if that is the rule. A suppression preference should survive. A held record should not enter outreach. This makes the test review specific rather than a general impression that the records look acceptable.
Inspect the import mapping screen column by column, run the controlled batch, and review the result in the record interface and available import report. Correct the mapping or file design if any expectation fails. Retest the affected case before proceeding. A small delay here is preferable to discovering the same defect across an entire campaign.
Worked example: a shared domain creates an identity conflict
In this fictional example, Northline Group and its subsidiary Northline Projects share a public domain. The incoming research concerns the subsidiary's service offering, while the existing CRM record represents the parent. A domain-only match would update the parent and attach the subsidiary's contact to it without acknowledging the distinction.
The reviewer marks the row as an identity hold and records the evidence for the subsidiary. The account owner decides how the organization's CRM model represents related entities. If separate company records are appropriate, the import uses the reviewed identifiers and associations required by that model. If the parent record intentionally represents both, the research finding is labeled with the subsidiary context so it is not mistaken for a group-wide fact.
The contact is not sent a message until the association and context are resolved. The corrected decision is added to the mapping notes for future imports. This example shows why a domain can be a useful identifier without being a complete business-entity model. The right result depends on the actual organization and the customer's CRM conventions.
Reconcile the batch using separate totals
Compare expected and actual company creates, company updates, contact creates, contact updates, held rows, rejected rows, and associations. Investigate differences by category. A row rejected for a property-format issue is different from a duplicate matched to an existing record. The correction should address the actual reason rather than simply reimporting the entire file.
Keep a row-level outcome ledger with source key, intended action, resulting CRM ID, result, and corrective action. If a subset fails, repair that subset and preserve the successful results. Repeating the full batch without reviewed identifiers can create duplicates or overwrite newer work. The ledger makes a targeted repair possible.
Inspect a sample of successful records as well as failures. Import errors identify only some problems. Wrong object mapping, incorrect associations, and unintended owner changes can be accepted technically. The reviewer should verify that the data supports the intended sales decision and that the record history remains coherent.
Diagnose common mapping and update problems
If a field is absent from the mapping options, confirm the selected object and the property's existence and permissions. If values are rejected, compare the source type and allowed values with the destination definition. If dates appear wrong, inspect the source format and the import's date interpretation. Repair the specific mismatch instead of converting every column to text.
If duplicates appear, trace the identifier actually mapped for each object. Check whether the source contained blank identifiers, whether a source key was mistaken for a CRM ID, and whether an uncertain domain should have been held. If an existing contact's identity changed unexpectedly, compare the imported email and record ID with the intended update.
If associations are wrong, inspect the join columns and repeated rows in the prepared file. A spreadsheet sort applied to only part of the data can detach people from companies while leaving each cell individually plausible. Return to the unchanged raw file, rebuild the reviewed relationship map, and test the corrected case before repairing the full batch.
Release records to the owner with context
When reconciliation passes, move the batch to the agreed operational state and notify the responsible owner through the team's established process. Provide the batch identifier, what changed, unresolved holds, important limitations, and the location of supporting briefs. The handoff should explain what the team can now do with the data.
Do not describe imported research as qualified pipeline. A company fit score or sourced observation may support prioritization, but it does not establish a buyer's project, budget, or intent. The owner still needs to review the account context and decide whether communication is appropriate. Keep research acceptance separate from commercial qualification.
If StackShortlist supplies the research, check the delivered columns and identifiers against the public samples before you order. Email delivery or a customer-configured signed HTTPS webhook can support the handoff, but neither implies a native HubSpot connector or automatic synchronization. The customer controls property mapping, automation, permissions, and final import acceptance.
Make the post-import handoff explicit Transfer responsibility through acceptance rather than assuming an owner field completes the work.
Keep a repeatable import package
Retain the source file, prepared file, field map, expected-operation ledger, test results, import outcome, and correction notes together. Record the date and portal configuration assumptions. The next import should begin from this package, with a review of anything that has changed, rather than from an undocumented spreadsheet copied from an old campaign.
Assign ownership for maintaining the map when properties, workflows, or research fields change. A previously valid mapping can become wrong after a property is repurposed or an automation is added. Use a short change checklist and repeat representative tests after material changes. Reliable imports are a maintained process, not a one-time file conversion.
- Company and contact identifiers are distinct and reviewed.
- Custom fields have documented types, allowed values, and owners.
- Protected CRM information is excluded from unintended updates.
- Associations have a reviewed contact-company ledger.
- A representative test confirms both field values and downstream behavior.
- Final counts reconcile, failures are corrected selectively, and unresolved holds remain visible.
Common questions
Can company names alone prevent duplicates?
Names are useful for review but can change or be shared by unrelated businesses. Use the documented identifier strategy for the intended import, preserving existing Record IDs for reviewed updates. Treat ambiguous entity matches as holds rather than relying on a similar display name.
Should company and contact IDs share one column?
No. They identify different objects and should remain in clearly labeled columns. Map each to the correct object identifier during import. A source system's internal key should also remain distinct from a native HubSpot Record ID.
Can one company have several contacts in the file?
Yes, but the company identifier and the intended associations must be represented consistently. Repeated company information should refer to the same reviewed company record where appropriate. Count contacts, companies, and associations separately during reconciliation.
What should happen to blank research fields?
Decide the meaning of the blank in staging and test the destination behavior. Unknown, not researched, and not applicable are different states. Do not allow an unexamined blank to erase valid CRM information or become an invented value merely to make the file look complete.
Does this guide prove the file will work in my portal?
No. It provides a documented preparation method and fictional mapping specimen. Your properties, permissions, existing records, and automation require a representative live test in the appropriate controlled environment before a full import. Record and inspect the actual result.
Sources & further reading
Primary references support the technical details. Worked examples are illustrative; workflows and checklists are practical methods to adapt to your own process.
Something changed? Tell the editorial team.