HubSpot Integration

Updated 16 Oct 2026 by Haydn

The HubSpot integration keeps your partner programme and your HubSpot portal in step. Journeybee leads, deals, partners and partner contacts sync to HubSpot Contacts, Companies and Deals, and changes made in HubSpot flow back. Everything runs off your own field mapping, so you decide exactly which HubSpot objects and properties are involved.

Where to find it: Go to Settings, then Integrations. HubSpot sits under the CRM section.

Who can use this: Connecting and configuring the integration is admin-only. Once it is connected, anyone on your team sees the HubSpot links and linked deals on leads, deals, partners and contacts.

Before you start

Authorise with a HubSpot user who can read and write contacts, companies and deals, plus leads if you plan to use HubSpot's own Lead object. The connection runs as that user, so anything they cannot see or edit will not sync.
Decide where partner records should live in HubSpot: the standard Companies object, or one of your custom objects — custom objects need HubSpot Enterprise.
Decide how you identify a partner company in HubSpot, for example a Type = Partner property value. Partner import always needs it; partner sync needs it on the standard Companies object, while on a custom object it is an optional extra filter.
Set up your partner stages, deal stages and custom fields first, because the configuration screen maps against whatever exists at the time. See Stages and Custom Fields.

Connecting HubSpot

Go to Settings, then Integrations, and click the HubSpot card.
Click Connect and authorise Journeybee in HubSpot, choosing the account you want to sync.
Journeybee then creates a Journeybee property group in your portal and adds the identifier properties it uses to link records:
- Companies: Journeybee Lead Id (journeybee_lead__c) and Journeybee Partner Id (journeybee_partner__c).
- Contacts: Journeybee Lead Id (journeybee_lead__c) and Journeybee Partner Contact Id (journeybee_partner_contact__c).
- Deals: Journeybee Lead Id (journeybee_lead__c) and Journeybee Deal Id (journeybee_deal__c).
These hold the link between each HubSpot record and its Journeybee record, so do not delete them or hide them from the connected user. Reconnecting later is safe, because the setup skips anything that already exists.
Open Configure and set up your mapping. Nothing syncs until you do.

The configuration screen

The HubSpot configuration page has four areas in its sidebar:

Integration: the connection itself, plus Remove Integration if you ever need to disconnect.
Configure: all sync settings, field mappings and stage mappings, grouped into sections.
Import: load records from HubSpot and bring partners or deals into Journeybee.
Manage: back to all integrations.

Each section shows a status of Not configured, Configured or Changes pending, and mapping sections show how many of their mappings are complete. Use the search box, the Only unmapped filter and Auto-match, which fills in every field that has exactly one matching HubSpot property, to work through a long list, then save. Changes apply to future sync activity, not retrospectively.

Partner sync settings

Which HubSpot object should partners be stored in? Companies, or one of your custom objects. The partner-side labels on the screen then use that object's name. Changing it later keeps the mappings that also exist on the new object and clears only the partner field, stage, import and identifying-field mappings the new object does not have; automatic partner import restarts either way, so pick it before you map. Choosing a custom object needs the custom object permissions that come with HubSpot Enterprise; a connection that was not granted them lists the standard objects only. Reconnecting to a different HubSpot portal resets the choice to Companies and clears every partner-side mapping.
Identifying field: the property and value that marks a record as a partner, for example Type = Partner. On the standard Companies object it is required, together with a unique partner field, before partners can be matched or created. On a custom object every record is already a partner, so it is optional — set the property and its value together as an extra match filter, or leave both empty.
Should we create a new record as a Partner if we don't find one? The question is named after your partner object. Yes to have Journeybee create the record when no match is found, or No to leave it alone.
Unique partner field: pair a Journeybee partner field with a HubSpot property so an existing record is matched instead of duplicated. You can set a different pairing per partner type. On a custom object it is optional too: with none set, a partner is matched to the record whose name equals the partner name, using the Partner Name mapping under Partner Fields. A single match links, no match creates the record when creation is on, and several possible matches or a record already linked to another partner are left alone rather than guessed.
Unique partner contact field: Email, First Name or Last Name paired with the equivalent Contact property, to stop duplicate partner contacts.
Create partner in HubSpot once it reaches stage: set separately for referral and reseller partners, and only shown for a partner type that has at least one active partner stage. Pick a Journeybee partner stage and new partners are only created in HubSpot once they reach that stage or a later one. Leave it blank to create them as soon as they sync. This only affects creation; partners already linked to a HubSpot record keep updating whatever their stage.

Automatic partner import

The Automatic Partner Import settings, also in this section, let Journeybee bring in partner records from HubSpot on its own, using the identifying field you set under Manual Partner Import.

Automatically import new partner records from HubSpot: off by default. When on, every 15 minutes Journeybee looks for HubSpot records matching your Manual Partner Import identifying field that are not yet linked to a Journeybee partner. Each one is linked to an existing partner when its website domain or name matches, or otherwise created as a new offline partner with its HubSpot contacts. No portal invitations are sent. A record with no contact that has an email address is skipped, so add one in HubSpot or import that partner manually. A mapped custom field that does not fit the record is left empty instead, so a bad field value never blocks the import.
HubSpot field for partner type: choose a HubSpot dropdown property on your partner object, then map each of its values to a partner type (Partner type: Referral, Partner type: Reseller and so on). Automatically imported records get the partner type their value maps to, and a record with no matching value uses the Partner Type set in Manual Partner Import.

Lead and deal sync settings

One-way creation sync to HubSpot: new Journeybee leads and deals create records in HubSpot, but later Journeybee edits do not change them. HubSpot changes still sync back. Notes are not affected.
Auto-create deals from partner associations in HubSpot: a HubSpot deal associated with a known partner record creates a lead and deal in Journeybee, even if nothing was linked before. It needs Partner Sync Settings that can match the partner record, or the associated record to already be linked to a Journeybee partner. The lead takes its details from the prospect's contact on the deal; when the deal has no contact with usable details, the lead is named after the prospect's company on the deal instead, or after the deal itself.
Enable multi-pipeline deal mapping: route deals to different HubSpot pipelines based on a custom field value, configured per partner type in the Deal Pipeline Routing sections.
Choose how the integration should interact with existing objects: Link to existing objects, Link to existing objects with no attached partner, or Do not link to existing objects. This governs whether a match on your unique properties is adopted or a new record is created.
Auto-approve leads with no open HubSpot deal: off by default. When on, every new lead is checked against HubSpot for an open deal on the matching company or contact. If none is found, the lead is set to Accepted automatically and synced according to your other lead sync settings. If one is found, or the check cannot run, the lead stays New, is not sent to HubSpot, shows a Held for review banner listing the open deals, and the lead's assigned users and partner managers receive the Lead needs review notification. Setting the Lead Status to Accepted or Rejected ends the hold. Sent referrals and campaign leads are never checked, and partners are not told that a matching deal exists. See Notifications.
Sync sent-referral leads with HubSpot and Sync sent-referral deals with HubSpot: both off by default. Leads and deals you have sent out to a partner stay out of HubSpot, and HubSpot updates to them do not flow back, unless you turn these on.
Show account owner to partners: off by default. When on, partners see a read-only Account owner block on their leads and deals in the partner portal, listing the record owner's name, title, photo and email. The CRM is never named to the partner, and reassigning the owner stays in Journeybee.
Unique Contact, Company and Deal fields: pair a Journeybee field with a HubSpot property for each object to prevent duplicates. You can set a different pairing per partner type (referral and reseller).
Sync on Lead Status: restrict sync to leads with the statuses you tick (New, Accepted, Rejected). Deals follow their lead's status. Leave it empty to sync every status.
Lead note sync direction and Deal note sync direction: Journeybee to HubSpot only, or do not sync notes.

Field mapping

Field mapping is what actually turns sync on. A HubSpot object is only created or updated if you have mapped at least one property for it, so map only the objects you want involved.

Partner Fields: Journeybee partners to properties on your partner object, including Country, which pairs with a text or dropdown property — an incoming value is matched to a country by name, or by its two- or three-letter code, and left unchanged when nothing matches. Changes to a mapped partner name, website, email, phone, description, category, tier or country in HubSpot also update the partner in Journeybee, and an empty value leaves the Journeybee value as it is. A partner's Primary Domain is sent to HubSpot but never changed from it, because it controls portal access.
Partner Owner: a row in the Partner Fields mapping that pairs with a HubSpot owner property (such as HubSpot Owner ID) on your partner object. Journeybee writes the HubSpot owner whose email matches the partner's earliest-assigned user — matched by email, case-insensitively. It is set when the partner record is created and, on later updates, only when the record has no owner in HubSpot yet, so an owner you assign there yourself is never overwritten. Journeybee to HubSpot only. If the partner has no assigned user, or no HubSpot owner shares that user's email, the property is left empty and the rest of the sync is unaffected.
Partner Contact Fields: partner contacts to Contact properties, being First Name, Last Name, Email, Phone Number and Position/Job Title.
Contact Fields and Company Fields: Journeybee lead details to the prospect's Contact and Company. The lead's Company Name is offered on the Company mapping only — it is never written to the Contact.
Deal Fields: deal name, deal value, commission value, expiration date and deal custom fields.
Submitted By: offered on the Contact, Company, Deal and HubSpot Lead mappings, and pairs with a text property. It records who submitted the lead or deal in Journeybee, written as First Last (email), or just the name or email when only one is known. Journeybee to HubSpot only, and left empty when there is no submitter.
Lead Status: offered on the Contact, Company and HubSpot Lead mappings — not the Deal mapping — and pairs with a single-line or multi-line text property, or a single-select dropdown property you have created in HubSpot (HubSpot's own dropdowns, such as its Lead Status property, and multi-select or yes/no properties are not offered). It syncs the lead's Journeybee status — New, Accepted or Rejected — both ways, so HubSpot workflows can act on it, for example creating a deal when a lead is accepted, and editing the property in HubSpot updates the lead on the next sync. For a dropdown, name your options after the statuses: a value that names none of them leaves the lead as it is, and a status with no matching option is left out of the write and reported under Sync issues. A lead created from the Journeybee widget inside HubSpot starts in the status the record carries, instead of always New. While One-way creation sync is on, the value is written only when the HubSpot record is created, and a status your Sync on Lead Status selection excludes never reaches HubSpot — so the property can lag behind the lead, and a later HubSpot edit can push that older status back onto the lead.
HubSpot Lead Settings: if your portal has HubSpot's own Lead object, you can also sync Journeybee leads to it, with its own field mapping. For each enabled partner type — referral and reseller — a Create HubSpot Leads for row decides whose leads become HubSpot Leads: Always (the default), Never, or Only when the partner matches, which reveals pickers for partner categories and tiers. An empty picker means no restriction; when both are set the partner must match both. Distributor and partnerless leads always become HubSpot Leads. An ineligible lead is simply not synced to the Lead object: its Contact and Company sync as before and nothing is deleted or unlinked.

Custom fields appear alongside the standard ones, and only HubSpot properties that are writable and visible to the connected user are offered. For dropdown, multi-select and yes/no properties Journeybee matches each value to a HubSpot option by value or by label, so an option labelled the same in HubSpot syncs even when its stored option value differs; a value with no matching option is reported under Sync issues, where you are asked to add the option in HubSpot or rename the Journeybee option. The same label match applies coming back: a HubSpot option lands on the Journeybee option labelled the same, a yes/no value on a Yes or No option, and a value that matches nothing leaves the Journeybee field as it is.

Summary notes in HubSpot

Each synced HubSpot record can carry one summary note written by Journeybee, so your team can review a submission at a glance without leaving HubSpot. A Summary Note section sits at the bottom of the Contacts, Company and Deals tabs on the configuration page — and of the Leads tab when your portal uses HubSpot's Lead object — each with its own toggle, off by default, and its own checklist of fields.

Turn on Add a summary note to HubSpot contact records — or the equivalent on the Company, Leads or Deals tab — and tick the fields to include under Lead fields in the summary note (on the Contact, Company and Leads tabs) or Deal fields in the summary note (on the Deals tab). Standard and custom fields of any type can be included, including long text.
Each record gets its note the next time it syncs to HubSpot: one note linked to that record only, listing each chosen field as a label and value. Empty fields are left out, and a record with no values at all gets no note until something is filled in.
The same note is updated in place when the chosen fields change — a second note is never created. A note deleted in HubSpot is recreated on the next sync, and if every chosen field is later emptied the note reads No details provided.
Each note write also updates the record's Last Activity Date in HubSpot.
Notes flow from Journeybee to HubSpot only. Records created from HubSpot — through an import, a HubSpot-side change or the scheduled sync — never receive one, and a problem writing a note never holds up the rest of the sync.

Stage and pipeline mapping

Partner Stages: choose a dropdown property on your partner object, then map each Journeybee partner stage to one of its values. On a custom object that has pipelines, the pipelines are listed first as Pipeline: entries so a Journeybee stage can map to a real HubSpot stage instead; a single pipeline is preselected.
Deal Pipeline Stages: choose a HubSpot pipeline and map each Journeybee deal stage, per partner type, to a stage in it.
Deal Pipeline Routing: with multi-pipeline mapping enabled, choose which pipeline a deal lands in based on a field value, per partner type.
Stage changes stay in the deal's pipeline: updating a deal's stage in Journeybee writes the mapped stage in whichever pipeline the deal already lives in — it never moves the deal between pipelines. Only a change to the Deal Pipeline Routing field moves a deal, and a Journeybee stage with no mapping in the deal's current pipeline writes nothing. If Journeybee cannot read the deal's current stage and pipeline in HubSpot, it leaves them untouched while the other fields still sync.

Partner associations

These settings show the partner on the synced HubSpot records. Each can be set to No association (the default), a text property holding the partner's name, or a real linked record association:

Deal to Partner Company: associate the partner company with the deal, or write the partner name to a deal property.
Deal to Partner Contact: associate the partnership's primary contact with the deal, or write their name to a deal property.
Contact to Partner and Company to Partner: the same options for the prospect's contact and company records.
HubSpot Lead Partner Association and HubSpot Lead Partner Contact Association: when the Lead object is used, the same choices for the HubSpot Lead — except the linked associations are the default here, so a synced Lead is linked to its partner record and to every synced partner contact on it unless you pick otherwise.

Synced deals are also associated with the prospect's own HubSpot contact and company. When the Lead object is used, a synced HubSpot Lead is linked to the prospect's contact and company as well. Associations are made once per pair: if you remove one by hand in HubSpot, Journeybee will not put it back, but reassigning the partner, or recreating the HubSpot record, will re-run it.

When a partner is created in HubSpot or linked to a HubSpot record, its partner contacts that already sync to HubSpot are associated with the partner record too — the standard company-to-contact link on Companies, or your portal's default link on a custom object.

If your HubSpot portal defines its own association labels on the deal-to-partner link, choosing the linked record option also reveals one row per HubSpot label. Each row is a multi-select of partner attributes — partner type, category, tier, tag and partner dropdown custom-field values, each scoped to a partner type — and the label is applied on top of the link when a deal syncs to a partner carrying any of the picked attributes. Mappings saved before this layout carry over automatically. Labels are only ever added, and a label removed in HubSpot stays off; Journeybee never removes one.

What syncs and when

Journeybee to HubSpot happens within seconds of a change. Rapid edits are batched into a single write, so you get one clean update rather than a burst.
HubSpot to Journeybee runs on a schedule, every 15 minutes. Each run picks up HubSpot records changed since the last run that carry a Journeybee identifier property.
New HubSpot deals are the exception, because they come through in real time. A deal created in a mapped pipeline, on a company or contact that already carries a Journeybee lead id, is pulled straight in as a deal. If nothing is linked, it is created only when auto-create from partner associations is on.
Notes sync one way, from Journeybee to HubSpot. A lead's note is linked to its contact, company and HubSpot Lead, and a deal's note to its deal, so it shows on every related record.
Journeybee paces its calls to stay inside HubSpot's API limits, so a large sync catches up over several runs rather than in one burst.
No echo back to HubSpot: when a HubSpot record creates something in Journeybee — through an import, a new deal pulled in real time, or a scheduled sync — Journeybee does not update that HubSpot record. The only writes are the Journeybee identifier properties and, on a new deal, the link to the partner's record, which keep the records linked. Those writes can still trigger HubSpot workflows, so exclude the Journeybee properties from any workflow trigger that should not react to an import or sync.

Importing existing HubSpot data

Partners

In Manual Partner Import, pick the HubSpot property and value that identifies your partners, then choose the Partner Type for this import. Only one type can be imported at a time.
Open the Import tab and click Load records. Journeybee lists the matching partner records on the Partners tab, 50 per page, with their HubSpot contacts underneath — every associated contact with an email is a candidate. Use Search by name to find a record, the page controls to move through the list, and Select all on this page to tick a whole page. Your selections stay in place as you page, search and switch tabs.
Click Import in the bar at the bottom — it counts the partners, contacts and deals you picked. Each record becomes a Journeybee partner, with its selected HubSpot contacts added as partner contacts and the HubSpot IDs stored so future changes stay linked. The page reports the import's progress until it completes.

Imported partners are created as offline partners and their contacts are not invited automatically, so invite them from the partner page when you are ready. Records with no associated contact that has an email address are hidden from the list, and the list notes how many on the current page were hidden: add a contact with an email in HubSpot to import them. See Partner Contacts.

Only the custom fields that apply to the import's partner type are filled in, and a HubSpot value that does not fit a field — for example an option the field does not have — is left empty rather than failing the record.

Deals

Map your deal pipeline stages first, so imported deals land in the right stage.
On the Deals tab (Partners to Import Deals For), select the partners whose deals you want. The list is paged and searchable like the partners list, and shows how many unimported deals each one has.
Run the import. Journeybee creates a lead and deal for each HubSpot deal. Deals that already exist but are missing their link properties are repaired rather than duplicated, and the results screen reports how many were imported, repaired and skipped. An import sends no lead or deal notifications — the records simply appear.

Only one deal import can run at a time per connection, and your selection is cleared when the import starts so a retry never re-imports the same deals.

A deal imported straight into a won or lost stage is dated by its HubSpot close date in reports, not the day you imported it — so historical deals land in the period they actually closed. This applies to new imports only; deals brought in earlier keep their import date.

Working with HubSpot from Journeybee

Open in HubSpot: leads, deals, partners and contacts show a HubSpot link that takes you straight to the matching record.
HubSpot owner: a lead or deal shows the owner of its HubSpot record, and you can search your HubSpot owners and set one without leaving Journeybee. When the linked HubSpot record has been deleted or merged in HubSpot, no owner is shown — and on a lead whose linked company is the record that is gone, the linked contact's owner is shown instead when it has one.
Held for review: with Auto-approve leads with no open HubSpot deal turned on, a new lead that matches an open HubSpot deal shows an amber banner at the top of the lead panel listing each deal with its stage, amount and owner. Click a deal to open it in HubSpot, then set the Lead Status to Accepted or Rejected. The banner disappears once the status changes.
Linked deals: a lead lists the HubSpot deals on its linked contact or company and marks the ones already connected. Use Create deal from CRM to link an existing HubSpot deal to the lead and pull it in.

Sync issues

When a write to HubSpot fails — because a stored link no longer works, for example the linked record was deleted in HubSpot or the connected user cannot access it, or because HubSpot refuses the write itself, such as a required property being empty or a value outside a property's options — Journeybee reports it under Sync issues on the HubSpot configuration page. The panel sits between Reconnect and Disconnect integration and only appears while there is something open, so a healthy integration shows nothing.

Each entry names the Journeybee record and what went wrong. Depending on the issue, you can:

Relink partner: pick the HubSpot record the partner should sync to.
Clear link: remove the stored HubSpot link from the record, so the next sync can link or create it again.
Link to matched record: adopt the existing HubSpot record Journeybee found but could not safely link on its own.
Retry sync: re-run the sync for that lead or deal straight away.
Retry all: on a rejected group, re-run the sync for every record it covers — leads, deals, partners and partner contacts.
Dismiss: close an issue you have decided not to act on.

When HubSpot refuses a write outright — for example a required property is empty, a value is not one of the property's options, or a mapped property no longer exists in HubSpot — every record refused for the same reason is grouped into one entry, such as "HubSpot rejected 18 partner contacts: Property values were not valid". The entry tells you what to fix, and Show records lists the affected records. Once the cause is fixed, Retry all re-runs the sync for the whole group, up to 200 records at a time; a record can only be retried once every 5 minutes, and one that has since been deleted or archived in Journeybee is cleared instead of retried. The issue closes itself once a write to that record succeeds.

The panel also watches the setup itself: opening the configuration page checks the saved settings, and each problem found becomes an entry of its own — Partner Sync Settings that give no way to match a partner — on Companies a missing identifying field or unique partner field, on a custom object also a missing Partner Name mapping or an identifying field set without its value — an incomplete partner stage mapping, automatic partner import switched on without its identifying field or value, the chosen partner object no longer existing in HubSpot, or a saved mapping that points at a Journeybee custom field or HubSpot property that no longer exists. A settings entry clears itself once the setting is corrected.

Two more entries come from the writes themselves: an entry saying HubSpot rejected a field, which names the property left out of the last sync and tells you to check the field mapping and the value in Journeybee; and an entry saying a Journeybee option has no matching option in HubSpot, for a dropdown, multi-select or yes/no value that matches no option of the mapped property — add the option in HubSpot or change the Journeybee option to match. A rejected-field entry clears itself once a later sync writes the field.

An issue clears itself once a sync to that record succeeds, and fixing one is admin-only, like the rest of the configuration page.

If your partners live on a custom object, a link to a partner record can also fail because HubSpot has no association defined between the partner object and the record being linked. That surfaces as a configuration-level entry telling you to add the association in HubSpot under the object's association settings, then sync again — Journeybee cannot create the association for you. The entry clears itself once a link to that object succeeds.

If your partners live on a custom object and the connection was not granted HubSpot's custom object permissions, a Reconnect HubSpot, missing scopes entry appears instead. Partner sync for that object is skipped until you reconnect, and the entry clears itself once the permissions are granted. Records skipped while it was open are pushed again on their next edit.

Troubleshooting

Nothing is syncing at all. Check the section you expect to sync actually has field mappings saved. An object with no mapped properties is never created or updated.
A banner says HubSpot needs reconnecting. The connection has expired or been revoked and sync is paused. Admins also get an email. Open the HubSpot card under Settings, then Integrations, and connect again. Sync resumes on the next run.
A banner says Reconnect HubSpot, missing scopes. Your partners live on a HubSpot custom object and the connection was not granted the permissions it needs — custom objects require HubSpot Enterprise. Partner sync for that object is skipped until an admin clicks Reconnect and authorises again; everything else keeps working.
Changes in HubSpot take a while to appear. That direction runs on a 15-minute cycle. Check too that the HubSpot record still has its Journeybee Id property populated, because clearing it unlinks the record.
A new HubSpot deal did not create anything in Journeybee. Real-time deal creation only covers deals in a pipeline you have mapped, on a record that carries a Journeybee lead id. For everything else, turn on auto-create from partner associations and make sure Partner Sync Settings are configured.
Duplicate contacts or companies are being created. Set the unique Contact, Company and Deal fields, and choose a linking option other than Do not link to existing objects.
Writes fail on a property. HubSpot rejects the write if the property is read-only, hidden, or of an incompatible type. Pick a different property in the mapping, or adjust it in HubSpot.
Imported partners cannot sign in. That is expected, because imports do not send invitations. Invite the contacts from the partner page.
A new lead says Held for review: the HubSpot check could not run. Journeybee could not confirm whether HubSpot has an open deal, for example because the connection needs reconnecting or the lead has no email or mapped unique field to match on. The lead is kept in New and out of HubSpot until you set its Lead Status yourself.
Sent referrals are missing from HubSpot. The two sent-referral toggles are off by default. Turn them on if you manage sent referrals in your own pipeline.

Good to know

Everything is opt-in. A setting you leave blank simply means that behaviour is off: no properties are written and no records are associated by default.
A HubSpot privacy deletion for a contact automatically clears that lead's personal details (name, email and phone number) in Journeybee.
Partner stage thresholds and per-partner-type lead and deal fields apply to referral and reseller partner types.
The Journeybee properties added at connect time are how records stay matched. Keep them on your objects and readable by the connected user.
Removing the integration stops all syncing but leaves your Journeybee records, and your HubSpot records, exactly as they are.
For the other tools you can connect, see Integrations.