Skip to content

Understand your data sync field mappings

Last updated: June 12, 2024

Available with any of the following subscriptions, except where noted:

All products and plans

All data sync apps have a set of field mappings that keep data in sync between HubSpot and your third-party app. To view what default mappings are available for an app, consult the app's marketplace listing page.

If you have a paid Operations Hub subscription, you can create and customize data sync field mappings. 

Review how HubSpot properties sync to third-party app fields, and vice versa below: 

HubSpot properties Third party app fields
Text Text
Number Number
Date picker Date picker
Datetime Datetime
Date picker Datetime
Datetime Date picker
Single checkbox Boolean
Radio select Radio select
Dropdown select Picklist

Additionally, the following fields in the third-party app can be mapped one way to any HubSpot text field:

  • Number
  • Date picker
  • Datetime
  • Single checkbox
  • In most apps, this is also true for owner fields.

The following HubSpot property types can be mapped one way as text to your third-party app's text fields:

  • Number
  • Date picker
  • Datetime
  • Single checkbox
  • Multiple checkbox
  • Calculation (number)
  • Score (number)

Please note: not all dropdown select properties can be synced two way between HubSpot and your third-party app. In this case, the dropdown select property can only be mapped one way as text to your third-party app's text field. 

For some third-party apps, HubSpot is unable to modify fields for the following reasons:

  • API limitations from the third-party app. 
  • Read-only fields in the third-party app. 

In this case, these fields will map one way from HubSpot to your third-party app. 

Review default data sync field mappings

Some property types have additional rules and considerations. Review the specific requirements for some default field mappings below.

Name properties

HubSpot has separate contact properties for First Name and Last Name. If your third-party app has only one contact property for the contact’s name, the data sync will consider the first word of the full name as the First Name in HubSpot, and anything that comes after the first space will sync to the Last Name property.

Third-party app HubSpot
Full name: John Jacob Jingleheimer Schmidt First Name: John
Last Name: Jacob Jingleheimer Schmidt

Please note: field mappings for both the First Name and Last Name properties must be turned on for the contact's name to correctly sync between HubSpot and your third-party app. 

Owner properties

Object record owners are synced using the Email Address property. If there is no email address, HubSpot will use the Name field for these owners. Record owners must be set up as users in both HubSpot and your third-party app for data sync to work. If a user exists in one app and not the other, data will not sync. 

If you have a paid Operations Hub subscription, you can map the Owner field in your third-party app to any custom HubSpot user property.

Dropdown select properties

When a sync is first created between HubSpot and your third-party app, HubSpot will sync all values and options of the dropdown property at the time. HubSpot will not automatically update the dropdown properties when new options are added. To update dropdown properties, you must save and start the sync between HubSpot and your third-party app again.

Address, Country, and Region properties

HubSpot structures the Street Address property as a single line text property, and the Country/Region property as a dropdown select property. Due to discrepancies with how other apps accept the formatting of these properties, address properties may sync as one-way mappings from the third-party app to HubSpot.

Association mappings

Turning on association mappings will sync any record associations from HubSpot to your third-party app, and vice versa. For example, contacts will be associated with their respective company or deal records. To prevent associations from being made, turn the association mapping off. Association mappings cannot be edited or deleted. 


Phone number

Some apps store multiple values for a property under different labels. For example, a single Phone property will have multiple labels for "Work", "Home", and "Mobile". In contrast, HubSpot has the following three default contact properties: Phone Number, Mobile Phone Number, and Fax Number

If a record is created in HubSpot by the third-party app, the phone number that is listed first in the third-party app will sync to the Phone Number property in HubSpot. Any additional phone numbers will not be synced unless they are labeled as Mobile or Fax. In that case, they will sync to the Mobile Phone Number and Fax Number properties respectively. 

phone number comparison

As long as there is a matching phone number in HubSpot and the other app, the phone number for that record is considered in sync across HubSpot and the third-party app. 

If none of the phone numbers match, HubSpot will follow the sync's conflict settings logic. If the sync is set to default to HubSpot, the phone number will be added to the list of phone numbers in the third-party app. If the sync defaults to the third-party app, the phone number in HubSpot will be overwritten by the number listed first in your third-party app. 

When HubSpot creates a new record in your third-party app, the Work label will be applied by default. 


Business units

If you have the Business Units Add-On, you can set up a two-way field mapping between the Business Units property in HubSpot and any custom multi-checkbox or text field in the third-party app. 

Deal stages, ticket status, or order status

To sync the deal stage, ticket status, or order status properties, the corresponding field in your third-party field must match the Label of the HubSpot property. For example, if your deal stage in HubSpot is Closed Won (Sales Pipeline), your third-party app's field must reflect the same label. 


Learn more about data sync.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.