HubSpot — field mapping & custom objects

This article covers how Katalyz properties map to HubSpot standard properties and custom objects.

For the primary field-mapping reference, see CRM field mapping & sync — that's the full admin article. This one focuses on integration-side specifics.

HubSpot objects supported

• Contacts
• Companies
• Deals
• Custom HubSpot objects (if your portal uses them)
• Tasks
• Timeline events

Mapping custom HubSpot objects

Mapping a custom HubSpot object follows the same flow as mapping any standard object — use the field-mapping UI documented in CRM field mapping & sync. Custom objects appear in the picker provided your HubSpot installation granted the crm.schemas.custom.read / crm.objects.custom.read|write scopes (see Connecting HubSpot).

Two screens, two jobs

Mapping is set in two places, and it helps to know which does what.

The property catalogue

Settings → Data → Custom objects lists your properties under three tabs — Rooms, Participants, Actions — with a Search box, a sort and a filter. Each row carries six columns:

• Property — its name.
• Origin — Built-in for the native, non-editable properties (Account, Deal, Dealroom name, Dealroom owner), Katalyz for ones created in your workspace, Imported from HubSpot for ones pulled from the CRM.
• Mapped with — either a chip with the HubSpot logo carrying the mapped property's name, or an Add mapping button when the property isn't linked to anything yet.
• Created by — the person's avatar.
• Used in — how many rooms carry a value for this field. Very useful before deleting or renaming anything.
• Description.

So this is where you see at a glance what isn't mapped yet: every row showing Add mapping.

The overview of active pairs

Settings → Data → Hubspot, the Synced fields panel ("Map your Katalyz fields to HubSpot properties").

Each row is one pair joined by a ⇄ arrow: a Katalyz field on the left, a HubSpot property on the right.

• + Add new mapping, top right, appends an empty row at the bottom of the list.
• Refresh list, beside it, re-reads the properties from HubSpot. Use it after creating a property on the HubSpot side so it shows up in the picker.
• The × at the end of a row deletes the mapping.

Two AI-written fields

Katalyz generates two values per room that are worth mapping on day one:

Both are refreshed as the room evolves, so the CRM record carries a current read on deal health without anyone updating it by hand. See AI settings.

Pre-built mappings

Apart from those two, there are no default out-of-the-box mappings. After connecting HubSpot you start with a clean slate — every other mapping is one you create explicitly via the field-mapping UI.

Importing fields from HubSpot — recommended

Rather than creating each Katalyz field by hand and then mapping it to a HubSpot property, import the fields straight from HubSpot. The app itself marks this path Recommended.

It doesn't happen on the Hubspot page but in Settings → Data → Custom objects. The + Add property button, top right, opens a dialog with two choices:

• Import from HubSpot (Recommended) — "Import a property directly from HubSpot. Its options and details will stay automatically synchronized over time."
• Create new property — "Create a new property that will exist only within Katalyz. You'll be able to map it to fields from external apps, but the options and details will not stay automatically synchronized over time."

That is, in one sentence, the whole difference between the two methods.

Concretely, when you import a HubSpot property:

• Katalyz recreates the same field structure on the Katalyz side — same type (text, number, date, dropdown…), same options for dropdowns (values and labels aligned), same formatting (currency, datetime, etc.).
• The mapping is created automatically — you don't have to re-point the Katalyz field to the right HubSpot property.
• Structure stays preserved: if you later add an option to a HubSpot dropdown, importing keeps both sides aligned.

Why it's better:

• Fewer errors — no divergent options between the two dropdowns (see below).
• Faster — one step per field instead of two (create + map).
• More reliable — the source of truth for field structure stays HubSpot; Katalyz mirrors it.

When does manual creation make sense? For fields that are Katalyz-only and aren't (and shouldn't be) in HubSpot — e.g. a field that's purely internal to in-room collaboration.

Field type compatibility

You cannot map two incompatible types: the HubSpot property list is filtered by the type of the Katalyz field picked on that row.

On an empty row:

1. The right-hand picker stays disabled until a Katalyz field is chosen.
2. Open the left-hand picker: Katalyz fields are grouped by object (Room…) with a Search box at the top. Fields already mapped on another row are greyed out.
3. As soon as a Katalyz field is chosen, the right-hand picker becomes active and offers only properties of a compatible type, themselves grouped by HubSpot object (Company…). Properties already used elsewhere are greyed out: a property is used once.

Two examples from a live portal:

So there is no correspondence table to memorise: if a property isn't in the list, its type doesn't suit the selected Katalyz field.

Dropdowns: the options have to match

The filter applies to the type, not to the values. Two dropdowns are always mappable even when their options differ — and that is the one mismatch the UI lets you create.

It isn't silent: the row shows a red badge to the right of the HubSpot property. Hover it and the tooltip says the options of the two fields don't look like they match, that sync may not work, and then lists what is missing on each side by name — missing in CRM: Not started, Qualified, Churned, missing in Katalyz: Oppty: DM & timing & pricing, Win: signed & payment tbd…

To fix it, align the options on both sides — or more simply import the field from HubSpot instead of recreating it by hand (see above): the import copies the options verbatim.

Related articles

• CRM field mapping & sync
• Creating custom properties
• Connecting HubSpot

Updated on: 04/10/2026