> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://katalyz.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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](https://katalyz.crisp.help/en/article/crm-field-mapping-sync-hubspot-salesforce-fzz4c/) — 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](https://katalyz.crisp.help/en/article/crm-field-mapping-sync-hubspot-salesforce-fzz4c/). 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](https://katalyz.crisp.help/en/article/connecting-hubspot-160gs96/)).

## Pre-built mappings

There are **no default out-of-the-box mappings**. After connecting HubSpot you start with a clean slate — every 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**. This is the recommended path for most cases.

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 type or option mismatch that silently breaks sync (see the compatibility table 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

| Katalyz field type | Compatible HubSpot types |
|---|---|
| **Single-line text** | Single-line text, Single-select |
| **Multi-line text** | Multi-line text |
| **Number** | Number |
| **Currency** | Number (with currency formatting) |
| **Date** | Date picker, Datetime |
| **Dropdown** | Dropdown (values must match) |
| **Phone** | Phone number |

Cross-type mapping causes sync to fail silently for that field.

## Related articles
- [CRM field mapping & sync](https://katalyz.crisp.help/en/article/crm-field-mapping-sync-hubspot-salesforce-fzz4c/)
- [Creating custom properties](https://katalyz.crisp.help/en/article/creating-custom-properties-1xr7pmy/)
- [Connecting HubSpot](https://katalyz.crisp.help/en/article/connecting-hubspot-160gs96/)