Cademy can send your customer and training data to HubSpot. This lets your team see learners, organisations, orders, course dates, registrations and Cademy messages alongside the information already held in your CRM.
This guide explains what the integration does and takes you through the full setup, one step at a time.
Allow about 20 minutes for the initial setup.
Before you start
You will need:
A Cademy account with the HubSpot app enabled. The integration is currently shown as an Enterprise beta feature.
Administrator access in Cademy.
Access to the HubSpot account you want to connect.
Either Super Admin access in HubSpot or the Developer tools access permission. HubSpot requires one of these to create and manage a Service Key.
If you cannot see HubSpot under Apps in Cademy, please contact Cademy Support before continuing.
Important: existing records are not sent automatically
Cademy starts sending records when they are created or changed after you connect HubSpot. It does not send all your existing Cademy records when you first connect.
For example:
A new learner created after setup will be sent to HubSpot.
An existing learner will be sent when their record is changed after setup.
An existing learner whose record does not change will not be sent.
There is currently no button to send all existing records. The Retry button in Sync Activity only works for a record that Cademy has already tried and failed to send.
Do not try to force a full sync by making bulk changes to your Cademy records. This can change important dates, trigger other integrations and send too much data to HubSpot at once. If you need historic data moved into HubSpot, contact Cademy Support before connecting.
How the integration works
The sync is one-way:
Cademy → HubSpot
Changes made in Cademy can be sent to HubSpot. Changes made in HubSpot are not sent back to Cademy.
Cademy never deletes a record from HubSpot. Turning off a module or disconnecting HubSpot stops future updates, but it does not remove information that has already been sent.
What can be sent
In Cademy | In HubSpot | Default setting |
Contacts | Contacts | On |
Organisations | Companies | On |
Orders | Deals | Off |
Course Dates | Marketing Events | Off |
Registrations | Marketing Event participant statuses | Off |
Messages | Email activities on a contact's timeline | Off |
Contacts and Organisations are turned on when you connect. The other modules are off so that you can review their settings before any data is sent.
Course Dates and Registrations use HubSpot Marketing Events. They need both Marketing Events scopes listed in Step 1. Cademy checks access when you test the connection, so use the result shown for that specific HubSpot account.
How records are matched
HubSpot data | How Cademy finds the same record again |
Contact | Email address on the first sync, then the stored HubSpot Record ID |
Company | The unique |
Deal | The unique |
Marketing Event | The Cademy course-date ID on creation, then the stored HubSpot Record ID |
Registration status | The Marketing Event and the learner's email address |
Email activity | The stored HubSpot activity ID, linked to the contact |
An existing HubSpot contact with the same email address can be updated on the first sync. Existing companies and deals normally have an empty Cademy ID property, so a similar name alone is not a match. If HubSpot already contains the same companies or deals as Cademy, plan how those records will be reconciled before turning on or triggering those modules to avoid duplicates.
If you connect more than one HubSpot account, Cademy sends new changes to every connection marked Ready. The Default label identifies your main connection, but it does not stop your other Ready connections from syncing.
Step 1: create a Service Key in HubSpot
A Service Key gives Cademy permission to use the parts of your HubSpot account needed for the sync. It does not give Cademy your HubSpot password.
Treat the key like a password. Do not put it in an email, ticket or shared document. After you save the connection, Cademy stores the key in encrypted form.
In HubSpot, go to Development → Keys → Service keys. This is HubSpot's current route.
You can also use HubSpot's Service Key guide if its menus have changed.
To create the key:
Click Create service key.
Enter a clear name, such as
Cademy HubSpot Sync.Click Add new scope.
Search for and select every scope in the table below.
Click Update to close the scope picker.
Check the list carefully, then click Create.
Open the new key if HubSpot takes you back to the Service Keys list.
Click Show, then Copy.
Scopes to add
Add all 14 scopes, even if you plan to leave some Cademy modules turned off at first. This makes it easier to turn them on later.
Scope | What Cademy uses it for |
| Checking which HubSpot account the key belongs to |
| Finding and linking HubSpot contacts |
| Creating and updating contacts, and logging message activity |
| Finding and linking companies |
| Creating and updating companies |
| Reading deal pipelines and deal records needed by the sync |
| Creating and updating deals |
| Showing HubSpot contact properties in Cademy's mapping screen |
| Showing HubSpot company properties in Cademy's mapping screen |
| Showing HubSpot deal properties in Cademy's mapping screen |
| Creating the property used to match Cademy organisations |
| Creating the property used to match Cademy orders |
| Checking access and reading course dates and registrations |
| Creating course dates and updating registration statuses |
HubSpot only lets you give a key permissions that your own HubSpot user has. If a scope is missing from the picker, ask a HubSpot Super Admin to create the key or give you the access you need.
You can edit the scopes on an existing Service Key later. If you add a missing scope, test and save the connection again in Cademy.
The connection test verifies the key, identifies the HubSpot account and separately checks Marketing Events. It does not exercise every Contacts, Companies, Deals or Schemas permission. A missing scope for those areas may first appear when you open mappings or when a record reaches Sync Activity. Adding all 14 scopes avoids that delayed failure.
Step 2: install the HubSpot app in Cademy
Sign in to Cademy Admin as an administrator.
Go to Apps.
Select HubSpot.
Read the summary, then click Install.
Cademy installs the app and opens the HubSpot connections page. Installing the app does not send any data. You still need to add a connection.
Step 3: connect your HubSpot account
On the HubSpot connections page, click Connect Your First HubSpot Portal. If another account is already connected, click + Add Connection instead.
In Connection Name, enter a name that will help your team recognise this HubSpot account, such as
Main HubSpot Portal.Paste the Service Key into Service Key.
Click Test & Continue.
Wait for Cademy to confirm that the connection succeeded.
Check the HubSpot Portal ID and data location shown on the Verify step. Make sure this is the HubSpot account you meant to connect.
Check the Marketing Events message. This tells you whether Cademy can use Course Dates and Registrations with this key.
Click Save Connection.
Click Finish.
Your first connection becomes the default connection automatically.
What Cademy adds to HubSpot
When you save the connection, Cademy creates two matching properties in HubSpot. It keeps them off your normal forms because they are for the integration to manage:
HubSpot object | Property label | Internal name |
Company | Cademy Organisation ID |
|
Deal | Cademy Order ID |
|
Cademy needs these properties to update the same company or deal each time instead of creating a duplicate. They are single-line text properties that require unique values. Cademy fills them in for you, so your team should not edit them.
Contacts do not need a separate matching property. On the first sync, Cademy uses the email address. After a contact has synced, Cademy stores its HubSpot Record ID and uses that ID for later updates. This means changing the email address in Cademy updates the existing HubSpot contact instead of creating a second contact. If that HubSpot contact was deleted or merged, Cademy falls back to an email-based upsert on the next sync.
If either property already exists, Cademy will use it only if it is a single-line text property with unique values required. HubSpot does not allow an existing property to be changed to require unique values later.
Step 4: choose what you want to sync
From Apps → HubSpot, select the connection you have just added. The Mappings page shows one card for each module.
Open each module, check its settings and click Save after making a change. Switching a module on does not send old records. It only allows new changes from that point onwards to be sent.
Contacts
Contacts sync to HubSpot Contacts. This module is on by default.
Cademy starts with these field mappings:
Cademy field | HubSpot property |
First Name | First Name |
Last Name | Last Name |
Phone | Phone Number |
Important points:
Email is used to match a Cademy contact to a HubSpot contact.
A contact without an email address is skipped.
If the Cademy contact belongs to an organisation and Organisations sync is on, Cademy also links the HubSpot contact to the matching HubSpot company.
Deleting a contact in Cademy does not delete the contact in HubSpot.
Organisations
Organisations sync to HubSpot Companies. This module is on by default.
Cademy starts with these field mappings:
Cademy field | HubSpot property |
Name | Company name |
Primary Domain | Company Domain Name |
The cademy_organisation_id property is always sent as well. It is managed by Cademy and is not shown as an editable mapping.
Deleting an organisation in Cademy does not delete the company in HubSpot.
Orders
Orders sync to HubSpot Deals. This module is off by default because deals can affect your sales pipeline, forecasts and reports.
Before turning it on:
Open Orders on the Mappings page.
Under Deal Pipeline, check the selected HubSpot pipeline and change it if needed.
Check Stage For Unpaid Orders. This is used for drafts, orders awaiting approval and orders awaiting payment.
Check Stage For Paid Orders. This will normally be a closed-won stage.
Check Stage For Cancelled Orders. This will normally be a closed-lost stage.
Turn on Orders Sync.
Click Save.
Cademy starts with these field mappings:
Cademy field | HubSpot property |
Order Reference | Deal Name |
Total Cost | Amount |
Close Date | Close Date |
Cademy also manages the deal pipeline, deal stage and cademy_order_id property automatically.
Order stages work as follows:
Draft, unpaid or awaiting-approval orders use your unpaid stage.
Paid or active orders use your paid stage.
Cancelled or fully refunded orders use your cancelled stage.
A partly refunded order stays in the paid stage.
Deals can also be linked to the matching contact and organisation when those modules are enabled.
Important: when a contact or order moves from one Cademy organisation to another, Cademy can add the new HubSpot company association but does not remove the previous association. Remove the old association in HubSpot if it should no longer be shown.
Deal amounts are written in your HubSpot account's currency. Cademy does not convert currencies. Make sure the HubSpot account uses the correct currency before turning Orders on.
Course Dates
Course Dates sync to HubSpot Marketing Events. This module is off by default.
Cademy checks Marketing Events access when you test the connection. If the module is unavailable, first check that the Service Key includes both Marketing Events scopes from Step 1. HubSpot's Marketing Events API guide lists the current requirements.
To turn it on:
Open Course Dates on the Mappings page.
Turn on Course Dates Sync.
Review the field mappings.
Click Save.
Cademy starts with these field mappings:
Cademy field | HubSpot field |
Course Date Name | Event Name |
Description | Event Description |
Join URL | Event URL |
Cademy always sends the start date, end date and cancellation status. These are automatic, so they do not appear in the editable field list.
If a course date is deleted in Cademy after it has synced, the Marketing Event is marked as cancelled. It is not deleted from HubSpot. A date deleted before it ever reaches HubSpot creates no Marketing Event.
For a multi-session block course, each real session syncs as its own Marketing Event. Cademy's internal block-parent placeholder is not synced.
HubSpot may not show a Marketing Event on its Events page until the event has at least one registrant. If you are testing Course Dates, also add a test registration before deciding that the event is missing.
HubSpot shows event dates in the viewer's local timezone and may use a US-style date format. Cademy also puts a readable date in the event name to make the event easier to identify.
Registrations
Registrations are stored as participant statuses on a HubSpot Marketing Event. This module is off by default.
Course Dates must also be on. A registration needs a Marketing Event to be attached to.
To turn it on:
Turn on and save Course Dates first.
Return to the Mappings list and open Registrations.
Turn on Registrations Sync.
Click Save.
There are no registration fields to map. Cademy sends one of these participant statuses:
Registered
Attended
Cancelled
If a learner is moved to a different course date, Cademy cancels their status on the old Marketing Event and registers them on the new one.
A registration needs the learner's email address. Registrations without an email address are skipped.
Registrations for on-demand or e-learning courses have no Course Date, so they are not synced. A registration on a multi-date block's parent placeholder is also skipped. Registrations attached to the real sessions can sync normally.
When attendance is marked as Attended, Cademy sends Registered first and then Attended so the learner appears in HubSpot's registration and attendance views. HubSpot has no separate Absent participant status, so a learner marked Absent in Cademy remains Registered in HubSpot.
Messages
Messages sync as email activities on the HubSpot contact's timeline. This module is off by default because it may add a large number of activities to HubSpot.
To turn it on:
Open Messages on the Mappings page.
Turn on Messages Sync.
Click Save.
There are no message fields to map. Cademy fills the activity fields automatically.
The activity can include the date, direction, sender, recipient, subject and a summary. For Cademy Inbox messages, it includes the message text and a link back to the conversation. For transactional emails, it records the subject but does not copy the full email body from storage.
A message is skipped when:
It does not belong to a Cademy contact.
The contact cannot be matched in HubSpot.
The message was blocked and was never sent.
It is a duplicate email notification for a Cademy Inbox message that is already being logged.
Step 5: change the field mappings, if needed
The starting mappings will be enough for many accounts. You can add your own Cademy fields and map them to suitable HubSpot properties.
To add a mapping:
Go to Apps → HubSpot and select your connection.
Open Mappings and choose the module you want to change.
Click Add Mapping.
Choose the Cademy Module.
Choose the Cademy Field.
Choose the HubSpot field on the right.
If both fields are dropdown lists, use Map values when the values in Cademy and HubSpot do not match exactly.
Complete or remove every unfinished row.
Click Save at the top of the page.
You can also remove a mapping using the remove button at the end of its row.
If the Cademy field you need does not exist yet, choose Create new field… from the Cademy Field list. Create the field, then continue setting up the mapping.
Keep these rules in mind:
Map fields that hold the same kind of information. For example, map a date to a date field and a number to a number field.
Do not map two Cademy fields to the same HubSpot property. Only one value can be kept.
Removing a mapping stops future updates to that HubSpot property. It does not clear the old value already stored in HubSpot.
Mapping changes are not applied to old records automatically. They are used the next time each Cademy record changes.
The Cademy matching properties, deal pipeline, deal stage, course date times and cancellation status are managed automatically and cannot be changed through field mappings.
Step 6: test the setup
Use a new test record rather than changing a large number of real records.
Create a test contact in Cademy with an email address you can recognise.
Wait a short time, then search for that email address in HubSpot.
In Cademy, open Apps → HubSpot, select the connection, then open Sync Activity.
Confirm that the contact shows as Synced.
If you enabled other modules, test them one at a time:
Create or update a test organisation.
Create a test order and check its deal pipeline and stage.
Create or update a course date and check its Marketing Event.
Create, attend, move or cancel a test registration and check its participant status.
Send a test message linked to the contact and check the contact's HubSpot activity timeline.
Check Sync Activity
Open Apps → HubSpot, select a connection, then select Sync Activity.
This page shows the 100 most recent sync records for that connection. You can filter the list by:
Synced
Failed
Needs reconnect
Each row shows the Cademy record, the HubSpot record ID when available, the last attempt and the latest error.
If a row says Failed:
Read the error message.
Fix the cause in Cademy or HubSpot.
Click Retry on that row.
Retry sends that one record again. It does not resend other records and it does not send records that have never been attempted.
If a row says Needs reconnect, replace the credentials as explained below. Retry is not available until the connection works again.
Some records are deliberately skipped, such as a contact with no email address. Skipped records may not appear in Sync Activity.
Replace, rotate or update a Service Key
HubSpot recommends rotating Service Keys regularly. It also lets you add or remove scopes on an existing key.
To replace the key stored in Cademy:
In Cademy, go to Apps → HubSpot.
Open the action menu on the affected connection.
Click Edit Connection.
Paste the current or replacement Service Key.
Click Test & Continue.
Check the Portal ID carefully.
Click Update Connection, then Finish.
Cademy will not let you replace a connection's key with one from a different HubSpot account. Add a new connection for the other account instead.
For planned rotation, choose HubSpot's Rotate and expire later option. HubSpot keeps the old key working for seven days while you update Cademy. After Cademy accepts the new key, you can let the old one expire.
If a key may have been exposed, use Rotate and expire now, then update Cademy immediately.
Updating or rotating a key does not remove your mappings.
Disconnect a HubSpot account
Go to Apps → HubSpot.
Open the action menu on the connection.
Click Disconnect.
Confirm Disconnect.
Syncing to that account stops. Existing HubSpot contacts, companies, deals, Marketing Events and activities stay in HubSpot.
You can reconnect later by choosing Edit Connection and entering a valid Service Key.
Common problems
I cannot see the HubSpot app in Cademy
The HubSpot feature may not be enabled for your account, or you may not be a Cademy administrator. Ask your Cademy account owner or contact Cademy Support.
I cannot create a Service Key in HubSpot
You need to be a HubSpot Super Admin or have the Developer tools access permission. Also check that you are in the correct HubSpot account.
A scope is missing from the Service Key picker
HubSpot only lets you grant permissions your own user already has. Ask a HubSpot Super Admin to create the key or update your permissions.
The connection test says a scope is missing
Open the Service Key in HubSpot.
Click Edit.
Add the scope named in Cademy's error message.
Return to Cademy and choose Edit Connection.
Paste the key again and complete the test and update steps.
Course Dates or Registrations says Marketing Events is unavailable
Check that the Service Key has both of these scopes:
crm.objects.marketing_events.readcrm.objects.marketing_events.write
Then use Edit Connection in Cademy to test the key again. If both scopes are present and the module is still unavailable, contact Cademy Support with the exact message shown during the test.
Organisations or Orders do not sync
Cademy may have been unable to create its matching property.
Check that the Service Key contains crm.schemas.companies.write and crm.schemas.deals.write.
Also check whether a HubSpot property already uses either of these internal names:
cademy_organisation_idcademy_order_id
If one already exists, it must be single-line text with unique values required. HubSpot cannot add the unique-values setting to an existing property later, so a wrongly configured property must be renamed or removed in HubSpot. After fixing it, use Edit Connection in Cademy to test and save the key again.
A contact or registration did not sync
Check that the contact has an email address. HubSpot uses email to match contacts and Marketing Event participants.
Also check Sync Activity for an error. HubSpot may reject an address that another system accepted.
I turned Orders on, but orders still do not sync
Open Orders under Mappings and check that a pipeline and all three stages are selected. Then click Save.
A course date synced, but its learners did not
Course Dates and Registrations have separate switches. Make sure both modules are on and saved. Also check that the learners have email addresses.
Messages are not appearing on a contact's timeline
Make sure Contacts and Messages are both on. The message must belong to a Cademy contact that can be matched in HubSpot. Blocked messages and duplicate Inbox notifications are deliberately skipped.
I connected HubSpot, but no old records appeared
This is expected. Cademy does not perform a full historic sync when you connect. Records are sent when they are created or changed after setup.
Everything now says Needs reconnect
The Service Key may have expired, been rotated or been deleted. Create or copy a valid key, then use Edit Connection in Cademy to replace the credentials.
I changed a field mapping, but old HubSpot records did not change
Mapping changes are used on future syncs. They do not update all old records. The new mapping is used when each Cademy record changes again.
Getting help
If you still need help, contact Cademy Support and include:
The name of the Cademy HubSpot connection.
The Cademy record that did not sync.
The status and full error shown in Sync Activity.
The time you last tried the sync.
Do not send your Service Key. Cademy Support does not need the key value to investigate a sync problem.