How to sync contacts and deals between Nuvia and HubSpot

Two-way sync keeps contacts, deals and pipeline data always up to date on both platforms.

Prerequisite: HubSpot integration connected and mappings configured.

---

How it works

Sync has two independent triggers: by field (Fields tab) and by funnel stage (Funnels tab). Mapping a field doesn't move a stage, and mapping a stage doesn't sync a field; if you need both, configure both tabs. The full map of what goes out, what comes in and how long it takes is in What Nuvia syncs with HubSpot and when.

Contact sync

• HubSpot → Nuvia: Contact created/updated in HubSpot → webhook → mapped fields updated in Nuvia.

• Nuvia → HubSpot: Contact created/updated in Nuvia → queue → mapped fields updated in HubSpot.

How Nuvia finds the contact in HubSpot

When syncing a contact from Nuvia to HubSpot, the platform looks up the matching record by email and phone in a single query. If the contact has an email in Nuvia, the email match takes priority over the phone match, which makes linking more accurate, especially when the phone format differs between the platforms. When there are multiple results, the oldest HubSpot record is linked.

The phone lookup covers the number in international format, with and without a space after +55. If the phone is stored in HubSpot in another format ((11) 99999-9999, 11999999999 without the country code, or with a ninth-digit difference), the lookup doesn't find the record and a new contact is created.

Why the same contact became two records in HubSpot

The cause is almost always a phone format mismatch. Two actions fix most cases:

• Standardize the phones in HubSpot in international format (+5511999999999)

• Fill in the contacts' email in Nuvia; when there's an email, it takes priority in the lookup and linking becomes much more accurate

For step-by-step fixes, see Troubleshooting the HubSpot integration.

Data pulled automatically

Company sync (enrichment)

When a company is created or has properties changed in HubSpot, Nuvia gets notified and enriches the matching company in your workspace. You don't need to configure anything beyond the connected integration.

What gets updated

Rules that always apply

• Nuvia never creates a company because of this notification. If no company in your workspace matches the domain received, nothing happens. Companies in Nuvia come from a real link with a lead

• Without a domain in HubSpot, nothing is done. The domain is what lets Nuvia find the right company

• Your manual edit wins. Fields you edited by hand in the company panel aren't overwritten by enrichment

• An empty field doesn't erase what's there. If the property isn't in the notification, the current value is kept

• The main domain doesn't change identity. If the HubSpot company is recognized by a secondary domain of the Nuvia company, the other fields are enriched, but the main domain stays the one already on the record

• Secondary domains are cleaned up before saving. Nuvia splits the list, removes duplicates and discards values that clearly aren't domains

Conversation link sync

Nuvia can automatically send the direct link to each conversation to HubSpot. That way, anyone on the team who opens the contact in HubSpot can open the conversation in Nuvia with one click, without searching manually.

How to set it up

1. Go to Integrations > HubSpot > Fields

2. Click add mapping

3. In the Smart Field column (right), select Conversation link — it's in the Conversation group

4. In the HubSpot property column (left), choose the contact property where the link will be saved (e.g. a custom property such as nuvia_link)

5. Click Save mappings

How it works

When a conversation is created in Nuvia, its direct link (in the format https://app.nuvia.ai/messages/conversation/{id}) is automatically sent to HubSpot in the mapped field. It's sent through the asynchronous queue, just like the other synced fields.

Scheduled meeting date sync

When the Smart Funnel books a meeting on the customer's calendar, Nuvia can save the date and time of that meeting to a HubSpot property. That way the sales team sees the appointment right in the CRM, without opening the conversation.

How to set it up

1. Go to Integrations > HubSpot > Fields

2. Click add mapping

3. In the Smart Field column (right), select Scheduled date; it's in the Conversation group

4. In the HubSpot property column (left), choose a contact date/time property where the value will be saved

5. Click Save mappings

How it works

The synced value is the start of the meeting recorded in the conversation. It travels in the same sync cycle as the other fields (such as Summary, Temperature and Lead Score); there's no separate trigger or extra setting.

If the meeting is canceled, Nuvia sends the field empty to HubSpot, clearing the value that had already been synced. Conversations without a scheduled meeting don't change the property.

Deal sync

The relationship between Nuvia funnel stages and HubSpot deal stages is defined in the Funnels tab. Each mapping row has three columns: Stage → Destination (the funnel stage and the matching deal stage), Synced Objects (the Contact, Deal and Lead switches) and Direction.

Sync direction (per stage)

Direction is defined per stage, in the Direction column of the mapping:

Advanced: the same stage in two funnels of the same object

A Nuvia stage can be mapped to more than one funnel of the same object in HubSpot. The most common case is the contact, which has two independent funnels in HubSpot:

• Lifecycle Stage (lifecyclestage) → the contact's lifecycle stage

• Lead Status (hs_lead_status) → the contact's lead status

You can map the same Nuvia stage to both at once: just add two mapping rows for that stage with the Contact object, each pointing to a different funnel. When the conversation reaches that stage, Nuvia updates all mapped properties; in the example, lifecyclestage and hs_lead_status.

When the deal isn't moved

Before moving a deal, Nuvia checks its current status in HubSpot and doesn't write in two cases:

• Deal already closed (won or lost) in HubSpot: it isn't moved

• Stage earlier than the current one: the deal doesn't move backward

In both cases the deal stays as is and the event is recorded in History, with no error. These safeguards apply only to deals: contact stages (Lifecycle Stage and Lead Status) and lead stages are written directly, even if they represent a step back.

The check depends on Nuvia being able to read the funnel in HubSpot. If the read fails, or if the deal's current stage isn't found in the funnel, Nuvia writes anyway; the safeguard doesn't block as a precaution.

How many deals a contact can have

The deal is linked to the conversation, but Nuvia doesn't blindly create a new deal: before creating one, it searches HubSpot for a deal already associated with that contact in the same funnel and reuses that record. So two conversations with the same contact mapped to the same funnel share the same deal.

Two deals appear when the conversations are mapped to different funnels in HubSpot, when the contact wasn't yet linked to a HubSpot record at creation time, or when the lookup of associated deals fails.

Create Leads in HubSpot by stage

Besides contacts and deals, Nuvia can automatically create Leads in HubSpot as the conversation moves through the funnel stages. In the stage mapping (Integrations > HubSpot), each stage has the Contact, Deal and Lead switches.

• Lead (per stage) → when the conversation reaches that stage, Nuvia creates a Lead in HubSpot. It's an upsert: if the contact already has a Lead, it's linked/updated instead of duplicated.

• Lead label → this field appears when the Lead switch is on. It defines the lead's “stage” at that step (e.g. WARM). In HubSpot, Leads don't have a pipeline — the stage is exactly this label (hs_lead_label). Turning off the switch discards the label when you save (no ghost label is left).

• Lead name template → below the deal name template, defines how the Lead is named in HubSpot, with the same variable autocomplete as the other templates.

Lead triggers, owner and display

• Campaigns: trigger events include Lead created and Lead updated, in addition to contact/deal events.

• Owner: in owner sync (Integrations > HubSpot > Users), the Sync source also accepts Lead Owner, in addition to Contact Owner and Deal Owner.

• Contact panel: in the HubSpot accordion (contact drawer), the Lead ID block appears, with a link to the record in HubSpot and a copy button.

Owner (agent) sync

When the Contact Owner or Deal Owner changes in HubSpot, Nuvia can automatically update the agent assigned to the contact's open conversation. This is useful for keeping traceability when the responsible salesperson changes in the CRM.

How to turn it on:

1. In Integrations > HubSpot > Users, set the Sync source (Contact Owner, Deal Owner or Lead Owner) and map the HubSpot users to the Nuvia users

2. In Integrations > HubSpot > Advanced, turn on the Update the owner when the Contact/Deal is updated in HubSpot toggle

Behavior:

Monitor history

1. Go to Integrations > HubSpot > History

2. Filter by object, direction, status and period

3. Click any record to open the sync details panel

Event types in the history

The history shows a friendly label for each event (instead of the technical name), and you can filter by it. Among the stage change events by object:

Sync statuses

See why a sync failed

When you open a record with Partial or Failed status, the details panel shows:

• Summary of the operation (what was synced)

• Error → the actual message returned by HubSpot. When a property fails HubSpot's validation, you see the exact cause: which object (contact or deal) and which property failed

• Technical details → the full HubSpot error body, useful for adjusting the field mapping

Why a contact didn't enter a campaign

When a HubSpot event should trigger a campaign and the contact isn't enrolled, the history records the reason it was skipped. Open the matching record and see the reason. The most common ones are:

Unlink a contact from HubSpot

You can remove the link between a contact in Nuvia and the matching record in HubSpot. After unlinking, changes in HubSpot no longer update that contact in Nuvia (and vice versa) until a new link is created.

Step by step

1. Go to Lists and Objects > Contacts

2. In the list, find the contact linked to HubSpot

3. Click the three-dot menu on the contact's row

4. Click Unlink HubSpot

5. A confirmation modal appears: “Unlink contact from HubSpot? The HubSpot ID will be removed from this contact. You'll need to relink it manually to sync again.”

6. Click Unlink to confirm

What happens

• The HubSpot link fields (external ID, CRM type and last sync date) are removed from the contact

• Two-way sync for that contact stops

• The contact still exists in Nuvia with all its data; only the link with HubSpot is cut

• To relink it, you'll need a new manual mapping or a reimport

Import lists from HubSpot

1. In the HubSpot integration, open Lists

2. Search for the list you want

3. Click Import members

Frequently asked questions