Skip to main content

HubSpot Sync

Sync data between Gravity Rail and HubSpot so your CRM stays current without manual work. Push member updates to HubSpot contacts, pull contact changes back into Gravity Rail, or run both directions at once. You control exactly which fields sync and how they're transformed along the way.

Record-source runs and previews​

Enabled form-submission, booking, deal and object sources run through Sync now and scheduled inbound sync even when Member sync is off. A Member-only run does not run record sources. Full re-sync rereads their remote items and updates their existing records by remote id.

Preview Sync skips form submissions, bookings, deals and objects. You can still preview Member sync when it is enabled. A connection with only record sources has no preview; use Sync now to run those sources.

Connect HubSpot​

You need a Gravity Rail workspace admin who can manage connections, and a HubSpot user who can install apps in your HubSpot account.

  1. In Gravity Rail, open Connections > Directory, click Add on HubSpot, then confirm Add.
  2. On the HubSpot page, click Connect HubSpot.
  3. Sign in to HubSpot, choose your HubSpot account, and approve access. HubSpot lists what Gravity Rail asks for: contacts, companies and deals, plus four optional permissions. Approve the optional ones for the features you plan to use: lists (import Members from a list or segment), owners (Contact owners), forms (form submissions) and Meetings links (bookings).
  4. HubSpot sends you back to the HubSpot page in Gravity Rail. The header shows Connected and your HubSpot Portal ID.

Nothing syncs yet. Turn on the parts you want on the Settings tab (next sections).

Add a permission later. If you skipped an optional permission, open the connection's three-dot menu and choose Reconnect, then approve it in HubSpot. Your settings and Member links stay.

Moving from your own HubSpot app. A connection set up earlier with your own HubSpot app's Client ID and Secret can move onto the Gravity Rail app. Open the Setup tab, click Use the Gravity Rail HubSpot app instead, and confirm. Your sync settings and Member links stay. If HubSpot asks you to approve access, sign in to the same HubSpot account that is connected now (details).

Disconnect. Disconnect in the three-dot menu stops Gravity Rail from using your HubSpot account. To remove the app from HubSpot too, uninstall it under Settings > Integrations > Connected Apps in HubSpot.

Before You Start​

You need a connected HubSpot account before you configure sync. If you have not connected HubSpot yet, open Connections > Manage and open Setup to connect it first. The connection header shows its status and Portal ID on every tab. Use its three-dot menu to reconnect or disconnect. Last synced, when present, opens the last successful real run on Sync.

Enabling Sync​

  1. Open HubSpot from Connections > Manage and select the Settings tab.
  2. You'll see a sync configuration for each entity type (e.g., members). Each entity type has its own toggles:
    • Enable outbound sync -- Pushes data from Gravity Rail to HubSpot.
    • Enable inbound sync -- Pulls HubSpot data into Gravity Rail.
  3. Turn on one or both directions for each entity type you want to sync.
  4. Click Save changes in the floating bar.

You can enable one direction and add the other later. If you're setting this up for the first time, starting with outbound only is a good approach -- it lets you verify your field mappings before pulling data back.

Save or Discard Settings​

Edits on Settings remain a draft until you save. The floating bar appears when you change a direction, mapping, record source, option-label selection, lifecycle stage or activity logging setting:

  • Save changes saves the whole Settings draft. Changes saved confirms success. Saving settings does not start a sync.
  • Discard restores the last saved settings.
  • If Save changes is disabled, the bar explains what to fix. For a record source, select an available Data Type and map at least one value to a Data Type field. Wait for the required catalogs to load, or retry a failed catalog request.
  • If a save shows Sync settings were not saved, your draft is kept. See When a Save Is Refused for each reason and what to change.

If you change tabs or follow a link with unsaved edits, Leave without saving? offers Stay to keep editing or Discard and leave to drop the draft and continue. Save first if you want to keep the changes. Reloading or closing the page also asks for confirmation while the draft is unsaved.

Entity Types​

The sync framework supports multiple entity types. Each connector supports a subset of these, and the available types are shown in the Settings tab:

Entity TypeDescriptionHubSpot Support
memberSync workspace members with external contacts/recordsYes
recordSync data records with an entity-type mappingNo (Monday.com in both directions; Salesforce outbound only). HubSpot form submissions, bookings, deals and custom objects come in through Records from HubSpot instead.
calendar_eventSync calendar eventsNo
fileSync filesNo

HubSpot's entity sync covers the member entity type, syncing workspace members with HubSpot contacts; its form submissions, bookings, deals and custom objects sync through Records from HubSpot (below).

The member entity type is required for a HubSpot connection, so the Members panel has no delete action. To stop syncing members, turn off both direction toggles and save. That keeps your sync rules and field mappings, which deleting the panel would remove.

Understanding Sync Rules​

A sync rule is a named group of field mappings that defines how a specific piece of data moves between Gravity Rail and HubSpot. Each rule has a name (like "Name" or "Email") and contains one or more operations in each direction.

Think of a rule as a container for related data. The "Name" rule, for example, sends a member's first and last name to HubSpot's first and last name properties (outbound), and brings HubSpot's first and last name back into the member's first and last name (inbound). Keeping these operations grouped under one rule makes them easier to find and manage.

Default Rules​

When you first enable sync, three rules are created automatically:

RuleOutbound (GR to HubSpot)Inbound (HubSpot to GR)
NameCopies the member's first name to firstname and last name to lastnameCopies firstname and lastname to the member's first and last name
EmailCopies the member's email to the HubSpot email propertyCopies the HubSpot email property to the member's email
PhoneCopies the member's phone to the HubSpot phone propertyCopies the HubSpot phone property to the member's phone

HubSpot has no middle name property, so a member's middle name is not sent, and syncing from HubSpot leaves it as it is.

Gravity Rail also keeps both of a contact's numbers, Mobile Phone Number and Phone Number, on the member. The mobile number becomes the member's main number; without one, the phone number does. To keep the contact's work number safe, sync never copies the mobile number into the HubSpot Phone Number property.

These defaults cover the most common fields. You can edit them, disable individual rules with their toggle switch, or delete them entirely if they don't fit your setup.

Creating a New Rule​

  1. In the Sync Rules card, click Add Sync Rule.
  2. A new rule appears with the name "New Rule." Click the name to rename it to something descriptive (e.g., "Company" or "Insurance Status").
  3. Click the chevron to expand the rule and see its outbound and inbound operations.
  4. Add operations in either or both directions (see sections below).
  5. Click Save changes in the floating bar when you're done.

Editing a Rule​

Each rule card shows a summary of how many outbound and inbound operations it contains (e.g., "2 out, 1 in"). Click the chevron to expand it and see the full details. You can:

  • Rename the rule by editing the text field in the header.
  • Enable or disable the rule with the toggle switch. Disabled rules are saved but skipped during sync.
  • Delete the rule with the trash icon. This removes it permanently.

Outbound Operations (Gravity Rail to HubSpot)​

An outbound operation takes data from a Gravity Rail member and writes it to a HubSpot contact property. Each operation has two parts:

  • Source (left side) -- What data to read from the member. Select from the dropdown or write a custom expression.
  • HubSpot property (right side) -- Which HubSpot contact property to write the value to. Open the dropdown and type part of the property's name or its internal name to find it among all your contact properties. Common properties such as Email and Phone are listed first.

To add an outbound operation, expand a rule and click Add outbound.

Source Options​

The source dropdown includes several categories of member data:

CategoryExamplesDescription
Core propertiesName, Email, Phone, Date of Birth, AgeStandard member fields
Data Type fieldsIntake: Status, Assessment: ScoreValues from Data Type records attached to the member
LabelsVIP, Active, At RiskWhether the member has a specific label applied
Custom ExpressionAny CEL expressionFull control over the value (see Expressions below)

Example: Syncing a Data Type Field to HubSpot​

Suppose you have a Data Type called "Intake" with a field called "Insurance Provider," and you want that value to appear on the HubSpot contact as a custom property:

  1. Expand your rule (or create a new one called "Insurance").
  2. Click Add outbound.
  3. On the left, open the source dropdown and select Intake: Insurance Provider from the list.
  4. On the right, search for your HubSpot custom property (e.g., insurance_provider).
  5. Save.

Now, every time a sync runs, each member's insurance provider value will be written to HubSpot.

Inbound Operations (HubSpot to Gravity Rail)​

An inbound operation takes data from a HubSpot contact and writes it to a Gravity Rail member. Each operation has two parts:

  • HubSpot source (left side) -- Which HubSpot property to read. Open the dropdown and type part of the property's name or its internal name (for example lifecyclestage) to find it among all your contact properties, or choose Custom Expression to write one.
  • GR field (right side) -- Where to store the value in Gravity Rail. The dropdown organizes targets into groups.

To add an inbound operation, expand a rule and click Add inbound.

Target Types​

When selecting where to store inbound data, the GR field dropdown offers three categories:

TargetWhen to use itExamples
Core PropertiesUpdate standard member fieldsName, Email, Phone
Notification opt-outsTurn off a member's SMS, calls, email or WhatsApp when HubSpot says the contact opted outOpt out of SMS when hs_sms_opt_out is checked
New Managed Field…Store data as a Synced field on the member, written by the HubSpot connection to its Synced fields Data TypeCompany name, job title, or any HubSpot property you want visible on the member profile

New Managed Field… asks for the field's key; the rule saves the key.

Note: HubSpot inbound sync does not write Labels or Data Type Fields. The dropdown offers only the targets this connection supports. If the dropdown is empty and Add inbound is unavailable, choose Refresh; your unsaved changes stay.

Example: Pulling Company Name into Gravity Rail​

To bring each contact's company name from HubSpot into Gravity Rail as a Synced field:

  1. Create a new rule called "Company."
  2. Click Add inbound.
  3. On the left, select company from the HubSpot properties dropdown.
  4. On the right, choose New Managed Field… and enter its key (e.g., hubspot:company).
  5. Save.

The company name will now appear on each member's profile after the next inbound sync.

Honor HubSpot opt-outs​

If your team records opt-outs in HubSpot, an inbound rule can turn off the matching channel in Gravity Rail. CRM sync is opt-out only: it can turn a channel off, but it never turns one back on.

  1. Create a new rule called "Opt-outs."
  2. Click Add inbound.
  3. On the right, under Notification opt-outs, choose the channel, for example Opt out of SMS when…
  4. On the left, choose the HubSpot property that records the opt-out, for example a checkbox property such as hs_sms_opt_out. A checkbox works as is. For any other property, write a condition that is true when the contact opted out, for example source.sms_status == "Opted out". A condition that does not give true or false is skipped and nothing changes.
  5. Save. Add one operation per channel you want to honor.

On the next inbound sync, each contact whose condition is true has that channel turned off. Gravity Rail then does not send on that channel. The sync log names the channels it turned off, and each change is recorded in the audit log.

To opt a member back in, change their notification settings in Gravity Rail. For SMS only, the member can also reply START to a text. Changing the value in HubSpot back does not turn the channel on.

Set each member's timezone​

Journey active hours use each member's own timezone by default; a member with none falls back to the workspace timezone. A journey set to Same time for everyone (workspace timezone) uses the workspace timezone for every member instead. To fill it from HubSpot:

  1. In the Settings tab, under Sync Rules, create a rule called "Timezone."
  2. Click Add inbound and set the target to Timezone.
  3. On the left, enter one of these custom expressions:
    • With a ZIP property: us_zip_to_tz(source.zip) != "" ? us_zip_to_tz(source.zip) : (us_state_to_tz(source.state) != "" ? us_state_to_tz(source.state) : us_phone_to_tz(source.phone))
    • Without one: us_state_to_tz(source.state) != "" ? us_state_to_tz(source.state) : us_phone_to_tz(source.phone)
  4. Save.

ZIP is the most accurate source and the phone area code the least: people keep mobile numbers when they move, and landlines can be ported. The phone step runs only when neither a ZIP nor a state gives a zone (absent, unknown, or a split state such as Texas). Each step returns an empty result instead of guessing, and an empty result never clears an existing timezone.

The Timezone target stores only standard zone names such as America/New_York. Map it with these functions, not a free-text HubSpot property ("Pacific Time"); a value that is not a standard zone name is skipped.

With Remote wins, a resolved step replaces the current timezone. With Keep local (see Conflict Policy), an existing timezone is never replaced, so the first zone set stays even if a ZIP arrives later.

Conflict Policy​

Conflict policy, in the member sync settings, decides what inbound operations do when a Gravity Rail field already has a value:

Conflict policyInbound behavior
Remote winsReplaces the Gravity Rail value with the HubSpot value. This is the default.
Keep localWrites only where no value is set. An empty HubSpot value still clears a Synced field; Member properties keep their own handling of empty values.

The policy covers member inbound operations only; outbound writes are not affected. A member's synced values are on the HubSpot connection's Data Type, on the member's Data tab: see The Data Tab.

Expressions​

Every source value in a sync operation is an expression written in CEL (Common Expression Language). Most of the time, you'll use the preset dropdowns and never need to think about this. But when you need more control -- splitting names, formatting values, or applying conditional logic -- you can select Custom Expression from the dropdown and write your own. See the Developer CEL reference for the full function and context reference.

How Expressions Work​

In an outbound expression, the variable source refers to the Gravity Rail member. In an inbound expression, source refers to the HubSpot contact. You access properties with dot notation:

ExpressionWhat it returns
source.nameThe member's full name (outbound) or contact property (inbound)
source.first_name, source.middle_name, source.last_nameThe member's first, middle and last name (outbound), each whole -- "Mara Lin" stays one first name
source.emailThe member's email address
source.phoneThe member's phone number
source.form_data.intake.statusThe "status" field from the member's "Intake" record

Available Functions​

CEL includes several built-in functions for transforming text:

FunctionWhat it doesExample
split(str, delimiter)Splits a string into a listsplit(source.name, ' ')[0] returns the first word
trim(str)Removes leading and trailing whitespacetrim(source.name)
lowerAscii(str)Converts to lowercaselowerAscii(source.email)
upperAscii(str)Converts to uppercaseupperAscii(source.name)
size(list)Counts items in a listsize(split(source.name, ' '))
contains(str)Checks if a string contains a substringsource.email.contains('@gmail.com')

Transform Presets​

The expression editor offers labeled presets for common transforms, so you don't need to write CEL for routine operations:

PresetWhat it doesExpression it generates
No TransformPasses the value through unchangedvalue
First NameExtracts the first word from a namesplit(value, ' ')[0]
Last NameExtracts the last word from a nameLast word of a space-separated string
Trim WhitespaceRemoves extra spacestrim(value)
LowercaseConverts to lowercaselowerAscii(value)
UppercaseConverts to uppercaseupperAscii(value)
Email DomainExtracts the domain from an email addressDomain portion after the @

For names, pick the member's First Name or Last Name source (source.first_name, source.last_name) rather than applying the First Name / Last Name presets to the full name: splitting the full name cannot tell a two-word first name like "Mara Lin" from a first and middle name.

Select Custom Expression from the dropdown when none of the presets fit your needs.

Conditional Logic​

CEL supports ternary expressions for conditional transforms. For example, to set a HubSpot property based on whether a member has a particular label:

"VIP" in source.labels ? "VIP" : "Standard"

Or to handle missing data gracefully:

source.email.contains("@") ? split(source.email, "@")[1] : ""

Sync Filters​

Each entity type can have optional outbound filter and inbound filter expressions. These are CEL expressions evaluated per entity before sync runs. If the expression returns a falsy value, that entity is skipped entirely -- no sync operations are performed for it.

Filters are useful for limiting sync to a subset of your data. For example, you might only want to sync members who have an email address, or only sync members with a specific label.

Outbound filters see the Gravity Rail member (source.name, source.first_name, source.middle_name, source.last_name, source.email, source.phone, source.form_data, source.labels, Member fields, and labels). Inbound filters see the HubSpot contact properties that were fetched (source.email, source.state, and so on) -- not member Data Type values or labels.

Label membership uses the label name, including its capitalization. For example, "VIP" in source.labels is true only when the Member has a label named VIP. Reading labels requires the labels:read scope.

Example Filters​

FilterDirectionWhat it does
source.email != ''outbound or inboundOnly sync when email is present
"VIP" in source.labelsoutboundOnly sync members with the "VIP" label
source.form_data.intake.status == 'completed'outboundOnly sync members whose intake record is completed
us_state_to_tz(source.state) != ""inboundOnly ingest contacts whose state maps to a single US timezone

HubSpot inbound is the scheduled poll only; targeted by-Id resync is a Salesforce feature.

Contact Owners​

Turn on Contact owners in the Sync tab to add each HubSpot contact owner as a Member. Each synced contact is then linked to its owner Member by a Contact owner relationship. When the owner changes in HubSpot, the link moves at the next sync. The link gives the owner no access to the contact's record.

At each sync:

  • An owner who is already a Member (same email) is linked to that Member. Otherwise a new Member is added with the External role and no login.
  • An owner Member that the sync added gets the owner's name and email from HubSpot at each sync. A Member linked by email keeps the details it has at every sync; only blank ones are filled. A Member who can log in keeps their own details.
  • Owner Members get the HubSpot owner label and one HubSpot team: … label for each of their current HubSpot teams. Other labels stay.
  • An owner HubSpot no longer lists loses these labels. The Member stays.

The step shows its state: Off, Needs permission, Syncing (owners are added at the next sync), the number of owners linked, or The last owner sync failed (it runs again at the next sync). When some owners are linked and some are not, the step also says how many could not be synced. That count includes an owner whose write or deactivation did not commit. Needs permission means HubSpot did not grant Read owners (crm.objects.owners.read). Reconnect HubSpot, approve that permission, then sync again.

Moving from the old owner options​

Before this change, owners came to Gravity Rail in two ways. This update changes both:

  • Contact Owner as an import option label. The update removes this selection. A sync rule that reads Contact Owner now gets HubSpot's owner id, not the owner's name. Turn on Contact owners to link each contact to its owner Member, then change or remove that rule.
  • The Contact owners Data Type. HubSpot stops updating this Data Type when the update arrives. The Data Type and its rows stay.

Import Option Labels​

In Settings → Import option labels, turn on listed enum properties to import their option labels instead of their stored values. The default remains stored values. Contact Owner is not offered here: use Contact owners above.

Save checks that the selected properties can provide labels. Disable outbound mappings to any property you select here: a label must not be sent back as a stored value.

Saving a changed selection resets the inbound scan. The next sync run reapplies contacts, including existing linked Members. Filters, identity matching and notification opt-out conditions still use raw values. Other inbound mapping expressions use the selected labels. Unknown IDs stay unchanged, and multiple selections keep semicolon separators. Label changes in HubSpot appear when contacts are next fetched, including full reconciliation.

Invalid or incomplete catalogs and the 30-second lookup deadline produce explicit errors. Removing label selections remains possible without calling HubSpot.

Default Lifecycle Stage​

When outbound sync creates a new contact in HubSpot (rather than updating an existing one), you can automatically assign a lifecycle stage. This is useful for ensuring new contacts enter your HubSpot pipeline at the right stage.

To configure this:

  1. Scroll to the Default Lifecycle Stage section below the sync rules.
  2. Select a stage from the dropdown: Subscriber, Lead, Marketing Qualified Lead, Sales Qualified Lead, Opportunity, Customer, Evangelist, or Other.
  3. Select None (do not set) if you don't want to assign a stage automatically.

This setting only applies to new contacts. If a contact already has a lifecycle stage set in HubSpot, it won't be overwritten.

Records from HubSpot: form submissions, bookings, deals and objects​

You can sync HubSpot form submissions, Meetings bookings, deals and custom objects into a Data Type you made in Gravity Rail. Each submission, booking, deal or object becomes one record for the member linked to its HubSpot contact.

  1. Create a Member Table, which holds many records for each member, with the fields you want to fill.
  2. On the HubSpot Settings tab, find Records from HubSpot and click Add form submissions, Add booking links, Add deals or Add custom objects.
  3. Pick the HubSpot form or booking link, or add the deal properties you want. For custom objects, pick the object (for example your insurance object), then add the properties you want.
  4. Pick your Gravity Rail Data Type.
  5. For each HubSpot value, choose the Data Type field it fills. You can also type a member field key to keep the latest value on the member too.
  6. Click Save changes in the floating bar.

The next sync adds the records:

  • Form submissions. Every submission is a new record, so a member who submits twice has two records. The member is found by the email on the submission.

  • Booking links. Every meeting booked through the link is a new record, with its start time, outcome and source. If the meeting is rescheduled or its outcome changes, its record updates. Booking-link sync is new: check your first booking arrives before relying on this Data Type to mean "booked".

  • Deals. Each deal is one record. When the deal changes stage, its record updates. A member with several deals has several records. If your HubSpot account renamed Deals (for example to "Engagements"), choose Deals.

  • Custom objects. Each object is one record for the member linked to its contact. Gravity Rail reads only the objects of contacts that are already linked to members; it never copies the rest of your HubSpot account. When an object changes, its record updates. When HubSpot deletes an object or no longer associates it with the contact, a later sync removes its record, and the source's Last check shows how many it removed when that is more than zero. When an object moves to another linked contact, its record moves to that contact's member. Gravity Rail removes only records this source wrote: records you entered by hand or imported are never removed. Custom objects need a HubSpot Enterprise account.

Submissions, bookings, deals and objects whose contact is not linked to a member are skipped, and so are those whose contact is linked to an archived member. After you link the member, run a sync with Full re-sync checked to read every submission, booking, deal and object again; records that already exist are updated, not duplicated.

"Reconnect HubSpot to grant access." Syncing forms needs HubSpot's forms permission, and choosing a booking link needs its meeting-links permission. Custom objects need their own read permissions; the object picker says when they are missing. Ask a HubSpot Super Admin to reconnect HubSpot and approve them, then check that the picker lists the object. Connections made before these features do not have these permissions. A saved deal source still syncs if its pipeline labels are unavailable; the labels stay empty. Choose Reconnect from the connection header's three-dot menu and approve the new permissions. If the connection already needs authorization, use the Reconnect button in the header. The form and booking-link pickers stay disabled until HubSpot grants the access they need. The object picker stays disabled until HubSpot grants custom-object access. If a catalog request fails, use Try again; the saved source stays in your draft.

Each source shows the result of its last check:

  • Succeeded — the last check worked. Last check counts show its record writes and items without a linked Member.
  • Reconnect HubSpot to grant access — HubSpot did not grant a permission this source needs. Use Reconnect in the connection header and approve it.
  • Not found in HubSpot — HubSpot cannot find the saved form when Gravity Rail reads its submissions. Pick another form, or remove the source.
  • Data Type refused the records — the Gravity Rail Data Type can no longer take them, for example because it was deleted. Pick another Data Type.
  • Last check failed — HubSpot did not answer. The next sync tries again.

A saved form or booking link can be absent from an incomplete picker list. The editor shows a separate notice for that case. Keep a valid saved source; that notice does not mean that HubSpot deleted it.

Running a Sync​

Manual Sync​

To run a sync manually:

  1. Go to the Sync tab (next to the Settings tab on the HubSpot page).
  2. The action bar starts a run: Preview Sync for a dry run, Sync Now to sync. A dry run never writes.
  3. To force a complete pass, tick Full re-sync first, then click Sync Now. It resets the sync checkpoints, so it does nothing on its own and a dry run ignores it. The directions themselves live on Settings.

An unscoped Sync Now run processes the enabled Member directions and enabled record sources. Record sources also run when Member sync is off. Preview Sync covers enabled Member directions and skips record sources; it is unavailable when only record sources are enabled. Progress streams live to your browser.

The Sync Now button sits in the top-right corner of the Sync tab. The Settings tab never starts a sync; it only saves what to sync.

Preview One Member's Write​

To check one member before you run a full sync, use Preview one Member's write on the Sync tab: choose a member and click Preview write. It shows the HubSpot contact the write would reach and every property value, and sends nothing. It is hidden while the connection needs reauthorization or is disconnected. See Write Preview for One Member.

Automatic Sync​

When sync is enabled, changes are also synced automatically. If a member's data is updated in Gravity Rail, the system triggers an outbound sync for that specific member. You don't need to configure this -- it's managed for you behind the scenes.

Viewing Sync Logs​

The Sync tab shows you what happened during each sync run.

Live Progress​

While a sync is running, you'll see:

  • A progress summary with processed, synced, failed, and skipped counts. A real run includes record-source results in these totals; the totals are not a count of distinct Members.
  • A live event log with Member results. Record-source results contribute to the summary; the source card in Settings shows its last check and counts.
  • A spinning sync icon on the Sync Now button while the operation is in progress.

Error Details​

If a member fails to sync, its row appears highlighted in red. Click on it to expand and see the specific error message. This is the fastest way to diagnose mapping issues.

Sync History​

Under Sync Runs, open a past run to review its status, timestamps, counts, and item results.

Synced fields​

When an inbound sync rule writes to a Member field, the value is a Synced field: the HubSpot connection stores it on its Synced fields Data Type (one record per member) and the member's Fields tab lists it with HubSpot as its source. The field is created when you save a rule that targets it, and keeps its values even after the rule is removed. The member's HubSpot contact ID is their Connection ID, changed only by linking or relinking. On the Fields tab, each connection's Synced fields and Connection IDs are grouped under that connection's name, below your own fields, with a link to open the connection's Data Type.

For example, if you create an inbound rule mapping HubSpot's company property to the key hubspot:company, every member matched to a HubSpot contact shows a "Company" field with the value pulled from HubSpot. You can rename the field on the Data Type; the key, and every rule and expression that uses it, stay the same. To change a value, edit the member's record on the connection's Data Type from the member's Data tab — depending on the connection's conflict policy, the next sync can replace your edit. See The Data Tab.

See Where HubSpot Keeps Its Data​

The read-only Data tab shows how the connection recognizes a member, which Data Types it keeps data in, and where every mapped field lives. The Data Type that holds your Synced fields is listed under Datasets. For what each dataset state and Field map column means, see Seeing Where a Connection Keeps Its Data.

Notes and Tasks​

Beyond field sync, you can configure automatic HubSpot note or task creation when records are saved. This uses templates with field variables (e.g., {{ record.data.status }}) to build the note or task content dynamically.

This is useful for creating an audit trail in HubSpot when specific actions happen in Gravity Rail -- for example, creating a HubSpot note every time an intake record is completed.

On Members, click Link Members. Choose one of the two paths in the Link Members? dialog:

  • Link Members starts a background pass that matches unlinked Members by email, then phone, and syncs their fields. Ambiguous or missing matches stay unlinked. This path creates no new Members or HubSpot contacts.
  • Review matches opens Review HubSpot matches. Click Find matches to search the first 50 unlinked Members. Review the proposed records, then click Link for a match or Link All for the displayed matches. This path also lets you restore a link after a prior unlink. A match is proposed only when the search finishes completely and finds exactly one contact, and never for a contact already linked to another Member or proposed to two Members. Email comes first; phone is used only when the Member has no email or the email found nothing. A Member with an ambiguous or unfinished search gets no proposal and can still be linked manually, for example through the Gravity Rail API.

Both paths require permission to manage Member links. Opening a dialog or searching for matches does not create a link; a Link action does. To bring in HubSpot contacts that have no Gravity Rail Member, use Import Members.

Import Members​

Click Import Members on the Members tab, then New import. You need workspace admin access; without it the button does not appear. Under Who to import, choose one way to select people:

SelectionWhat you choose
A HubSpot segmentOne of your contact segments (HubSpot's new name for lists). Search for it by name. Each segment shows its type when HubSpot reports one: Manual, Snapshot or Dynamic.
HubSpot contacts matching filtersUp to five filters on contact properties. Each filter has a property, a condition and a value. Type in the property box to search your properties by name.
A CSV file of idsA CSV file (5 MB at most) with a header row. Choose the column that holds the HubSpot contact ID.

A Dynamic segment updates itself from its filters, so its members change over time. Each run imports the people in the segment at that moment. Manual and Snapshot segments change only when someone edits them in HubSpot.

  1. Click Preview. Gravity Rail asks HubSpot who matches and shows the count and the first rows. A preview never creates or changes a Member.
  2. Enter an Import name, choose an eligible Member role for Members without Accounts, then click Save import. The picker offers External, Platform Support, and compatible custom roles. Admin, User, and Agent are not eligible. A role other than the safe default also requires role administration (member_roles:admin); see Roles and Permissions. These fields appear after a preview, and you must preview a selection before you can save it.
  3. Click Run on the saved import. The import runs in the background and links each contact to an existing Member when one matches, or creates a Member.

How Members Are Matched to Contacts​

When running a sync, the system needs to determine which HubSpot contact corresponds to which Gravity Rail member. It matches by email address or phone number. If a member has an email that matches a HubSpot contact, they're linked. If no match is found during an outbound sync, a new contact is created in HubSpot.

Troubleshooting​

A Segment Import Fails​

If a segment import says the connection is not allowed to read lists or segments, your HubSpot connection was authorized without that permission: reconnect HubSpot and accept it. If it says the selected list or segment was not found, the segment was probably deleted in HubSpot: open the import and choose another segment.

An Import’s Member Role Is Not Eligible​

Imports create Members without Accounts. Choose an eligible role in the import and save it again. If an older saved import stops with member_role_ineligible, change its role before running it again. Existing Members keep their roles. The legacy import endpoint still requires an eligible role when every contact matches an existing Member.

Member Email Address Is Not Valid​

HubSpot validates email formats strictly. If a member's email uses a non-standard format or domain (like .test or .example), HubSpot will reject it. Update the member's email to a valid address and re-run the sync.

A Mapped HubSpot Property Does Not Exist​

One of your outbound rules references a HubSpot contact property that doesn't exist. Open the Settings tab, expand the rule flagged in the error, and check the HubSpot property dropdown on each outbound operation. The property may have been deleted or renamed in HubSpot.

HubSpot API Rate Limit Reached​

HubSpot limits how many API calls can be made in a short period. If you hit this limit during a large sync, the system will retry automatically. For very large workspaces, the sync processes members in batches to stay within limits.

HubSpot Authentication Failed​

Your OAuth tokens may have expired or been revoked. Open HubSpot from Connections > Manage and reconnect the integration. You'll need to re-authorize with your HubSpot account.

Expression Returns Empty for Some Members​

If a CEL expression references Data Type values (like source.form_data.intake.status) but a member doesn't have a record for that Data Type, the expression returns an empty string. This is expected -- the field is simply not synced for that member. It's not an error.

Sync Button Is Disabled​

Sync Now requires at least one enabled Member direction or enabled record source. Save the configuration in Settings, then return to Sync. Preview Sync requires an enabled Member direction because it skips record sources. Record-only connections can use Sync Now and the inbound schedule. Their Check frequency control remains available in Settings when Member sync is off.

Tips​

  • Start with outbound only. Verify your field mappings work before enabling inbound. Check the Sync tab after your first sync to catch mapping issues early.
  • Use presets for common transforms. Custom expressions are powerful but easy to get wrong. The presets handle the most common cases (case conversion, whitespace trimming) reliably; for names, map the member's first and last name sources directly.
  • Name your rules clearly. When you have more than a handful of rules, descriptive names ("Insurance Info," "Enrollment Status") make it much easier to find what you're looking for later.
  • Check Synced fields on the member profile. After running an inbound sync, open a member's Data tab and check the HubSpot connection's Data Type shows the values you expect.
  • Channels -- Overview of all communication channels and integrations
  • Members -- Managing member profiles and data
  • Data Types -- Structured data collection used in sync rules
  • Labels -- Tagging and categorization for members