Every HubSpot integration project starts the same way: someone opens up a spreadsheet, lists the fields in the source system on the left, lists the HubSpot fields on the right, and draws lines between them.
This exercise is necessary. It's also where most integrations quietly go wrong.
Bad field mapping decisions don't usually fail loudly. They accumulate. A contact's name gets truncated because the source system allows 200 characters and HubSpot allows 128. A deal amount overwrites itself because the mapping logic doesn't distinguish between estimates and invoices. A status field gets mapped to the wrong property type and silently drops values it can't coerce.
Here's what experienced integration engineers pay attention to.
Understand the source system's data model first
Before mapping any fields, understand what the source system's objects actually represent. This sounds obvious but it's regularly skipped.
Clio has a "Contact" object and a "Matter" object. The matter is the legal case — it has a status, a practice area, a billing rate, and an open date. The contact is the client — they have a name, email, and address. These are not the same thing, and they should not both map to "contact" in HubSpot.
Matters map to HubSpot deals. Contacts map to HubSpot contacts. Getting this wrong at the start is extremely painful to fix later because you'll have hundreds or thousands of records in the wrong place.
Handle name fields carefully
Source systems frequently store names in different formats. Some use a single "full name" field. Others split first and last. Some have a prefix field (Mr., Dr., Esq.) that you need to decide whether to include.
HubSpot contacts have separate firstname and lastname properties. If your source system provides a full name field, you need to split it — and splitting names is harder than it looks. "John Smith" is easy. "Mary Jo Henderson-Clarke" is harder. "van der Berg, Jan" is a problem if you naively split on the first space.
Establish the name splitting logic before you sync any records. Cleaning this up after a large initial sync is tedious.
Don't map every field — map the fields that get used
There's a temptation to map every field in the source system into HubSpot. Don't do this.
Every extra field adds noise to the contact or deal record. It makes the record harder to read. It creates properties that nobody will maintain or act on. And it increases your surface area for data quality problems.
Map the fields that will be used in: - Reports and dashboards - Workflows and sequences - Personalization tokens in emails - Segmentation and list criteria
Everything else can stay in the source system. HubSpot is your action layer, not your archive.
Think about update logic, not just create logic
Most integration projects focus on the "create" path: how does a new record in the source system become a new record in HubSpot? But the harder problem is updates.
When an existing contact updates their email address in your source system, what happens? Does it overwrite the email in HubSpot? What if someone has manually corrected the email in HubSpot — should that update be preserved?
You need an update strategy for every field. Common options: - Source system always wins (overwrites HubSpot on every sync) - HubSpot wins if non-empty (source system only writes if the HubSpot field is blank) - Timestamp wins (most recently updated value from either system wins) - Manual wins (HubSpot updates are never overwritten by sync)
Different fields warrant different strategies. Phone numbers are usually fine with "source system always wins." Notes and manually-enriched data should usually use "HubSpot wins if non-empty."
Test with real data before going live
The final thing most teams skip: testing with real data instead of toy examples.
Your data model decisions will look reasonable in the abstract. They will reveal edge cases the moment you run them against your actual dataset. Common surprises:
- Source system has records with null values in required fields
- Date formats differ between environments (staging vs. production API endpoints)
- Some records have duplicate emails that violate HubSpot's deduplication logic
- Fields you assumed were single-value turn out to have multi-value entries in older records
Run your initial sync against a test HubSpot portal with a sample of real data before touching your production portal. It will surface problems in an environment where cleaning them up is easy.
One last thing: document your mappings
A mapping spreadsheet that reflects what actually shipped (not what you planned to ship) is genuinely valuable six months later when someone has to debug a data discrepancy. Keep it updated. Include the update logic for each field. Note any exceptions or custom handling.
Integrations that get documented are integrations that can be maintained by someone other than the person who built them.