This guide is for course providers connecting Cademy to HubSpot, a customer relationship management system (CRM). It explains how to send customer and training records to the intended HubSpot account, choose what is sent and check the results.
A connection links your Cademy account to one HubSpot account, also called a portal. A module is a group of records, such as Contacts or Orders. A field mapping tells Cademy which HubSpot property should receive each Cademy field.
Review your existing HubSpot data and agree which records your team wants to send before creating the connection. Setup time depends on access, existing records and the mappings you need.
Before you start
You will need:
A Cademy account with access to the HubSpot feature. Before it is installed, the HubSpot card on the Apps page is labelled ENTERPRISE and BETA; those labels alone do not confirm that the feature is enabled for your account.
System Admin access in Cademy, the staff role with full account access. Course Owner or Facilitator access alone does not open Apps.
Access to the intended HubSpot account, with Super Admin or Developer tools access permission to manage its Service Key.
If you are a System Admin and cannot see Apps, it has been hidden from your menu: look under More. If HubSpot is missing, unavailable or cannot be installed, contact Cademy Support to check feature access before continuing.
No automatic import of all existing records
Saving a connection does not send all existing records. With the connection Ready and the relevant module enabled, eligible new records and changes can trigger a sync. A sync can also send existing related records needed to connect that information.
For example:
A new contact with an email address can be sent when Contacts sync is enabled.
An existing contact can be sent when it is updated, or when it is needed by a syncing order, registration or message.
An unchanged organisation or course date can also be sent as a related record when its module is enabled. This is not a full historical import.
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.
The integration does not delete HubSpot records. However, deleting a previously synced course date can mark its event as cancelled, and registration cancellations or moves update participant statuses. Turning off a module or disconnecting stops future syncing through that setting; it does not undo data already 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 start enabled when you save a new connection. Review matching, duplicates and the data your team is prepared to send before Save Connection. The other modules start disabled.
Course Dates and Registrations use HubSpot Marketing Events, its event and participant records. They require the two Marketing Events scopes listed below. The connection test checks access to that area; it does not test every operation or send a sample record.
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 | Stored HubSpot Record ID after syncing; the unique |
Deal | Stored HubSpot Record ID after syncing; 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.
Each eligible connection marked Ready receives changes for its enabled modules. The Default label identifies the main connection; it does not stop other Ready connections receiving data. Check all connections when deciding where your records will go.
Step 1: create a Service Key in HubSpot
A Service Key is a secret credential that lets Cademy use selected parts of your HubSpot account. Each permission on the key is called a scope.
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, select Development, then Keys, then 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:
Select Create service key.
Enter a clear name, such as
Cademy HubSpot Sync.Select Add new scope.
Search for and select every scope in the table below.
Select Update to close the scope picker.
Check the scopes, select Create, then confirm creation when HubSpot asks.
Open the new key if HubSpot takes you back to the Service Keys list.
Select Show, then Copy.
Scopes to add
The complete setup uses the following 14 scopes. Ask the person responsible for your HubSpot account to review them, including the modules you plan to enable later. If a required scope is unavailable, resolve access before setting up the affected module.
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.
A successful connection test identifies the HubSpot account and checks Marketing Events access. It does not prove that every contact, company, deal, property or participant write will work. Check the saved mappings and actual sync results as well. Missing permissions can appear when loading mappings, creating matching properties or sending a record.
Step 2: install the HubSpot app in Cademy
Sign in to the Cademy admin dashboard as a System Admin, and confirm the intended course provider account.
Go to Apps.
Select HubSpot.
Read the summary, then select 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
Before saving: Contacts and Organisations begin enabled. Saving can make the connection Ready and eligible to receive changes before you select Finish. Existing matching HubSpot records can be updated. Confirm the intended portal, permissions and duplicate-handling plan first.
On the HubSpot connections page, select Connect Your First HubSpot Portal. If another account is already connected, select + 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.
Select Test & Continue.
If the test fails, read the message and fix the stated cause before continuing. A successful test opens the Verify step.
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 Marketing Events. An unavailable result needs an access check before Course Dates or Registrations can be used. If access is not established, it remains unconfirmed even if you can open those modules.
Select Save Connection.
Select Finish.
After Finish, check that the intended connection is listed as Ready. Open it to inspect Mappings. If Save reports an error, check the connection list before adding another connection; part of the setup can already have been saved. Give Support the connection name and error if the state is unclear.
Your first connection becomes the default connection automatically.
What Cademy adds to HubSpot
When you save, Cademy looks for these matching properties and attempts to create them if needed. New properties are excluded from HubSpot forms. A saved connection does not prove that both properties were created successfully: permissions or an existing incompatible property can prevent this.
HubSpot object | Property label | Internal name |
Company | Cademy Organisation ID |
|
Deal | Cademy Order ID |
|
Cademy creates these as single-line text properties with unique values. It fills them with Cademy record IDs to match companies and deals. Do not edit their values manually. If either module cannot sync, check its matching property and permissions using the questions at the end of this guide.
Contacts use the email address for initial matching, then the stored HubSpot Record ID for later updates. Changing a Cademy email therefore targets the linked HubSpot contact. If HubSpot reports that the stored record no longer exists, Cademy tries email matching again; check the resulting record when dealing with deleted or merged contacts.
An existing matching property must be writable, active and configured with unique values. If the expected property is incompatible, ask your HubSpot administrator and Cademy Support to agree a repair. Do not rename, remove or replace a shared property without checking its existing data and uses.
Step 4: choose what you want to sync
Select Apps, then HubSpot, and select the connection you have just added. The Mappings page shows one card for each module.
Open each module, review its settings and select Save after changing them. Check the saved confirmation, reload the module and confirm the intended setting remains. Enabling or changing a mapping does not run a historical import; later eligible changes and related-record syncs use the saved settings.
Contacts
Contacts sync to HubSpot Contacts. This module is on by default.
Review the starting field mappings shown for your account. The standard defaults are:
Cademy field | HubSpot property |
First Name | First Name |
Last Name | Last Name |
Phone | Phone Number |
Important points:
Email is needed for initial matching and a contact must still have an email address on later syncs. After a successful match, Cademy uses its stored HubSpot Record ID first.
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.
Review the starting field mappings shown for your account. The standard defaults are:
Cademy field | HubSpot property |
Name | Company name |
Primary Domain | Company Domain Name |
When an organisation syncs, Cademy also sends cademy_organisation_id. It is managed by Cademy and is not an editable mapping. The standard Primary Domain uses the first nonblank domain on the Cademy organisation.
Deleting an organisation in Cademy does not delete the company in HubSpot.
Name and domain changes, organisation merges and related-record syncs can trigger company updates. Do not assume that editing any custom organisation field immediately sends a company update. If an intended value does not reach HubSpot, give Support the field, record and time of the change.
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. Cademy uses this for active orders, including orders granted access before payment. Choose the stage that reflects this in your reporting.
Check Stage For Cancelled Orders. This will normally be a closed-lost stage.
Turn on Orders Sync.
Select Save.
Review the starting field mappings shown for your account. The standard defaults are:
Cademy field | HubSpot property |
Order Reference | Deal Name |
Total Cost | Amount |
Close Date | Close Date |
Cademy manages the pipeline, stage and cademy_order_id separately from field mappings. Close Date uses the payment date when recorded, otherwise the order creation date. One Cademy Order is one deal, including an Order containing more than one course.
Order stages work as follows:
Stage For Unpaid Orders is used for remaining orders that are neither active nor cancelled or fully refunded, including draft and pending orders.
Stage For Paid Orders is used for active orders that are not cancelled or fully refunded. Active does not always mean paid: access can be granted before payment.
Stage For Cancelled Orders is used for cancelled or fully refunded orders. This takes precedence over an active status.
A partial refund alone does not move an active order to the cancelled 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.
Select Save.
Review the starting field mappings shown for your account. The standard defaults are:
Cademy field | HubSpot field |
Course Date Name | Event Name |
Description | Event Description |
Join URL | Event URL |
Cademy sets cancellation status and sends usable start and end times automatically. These are separate from the editable mappings. If the default event name is used, it includes a readable course date when one is available; a custom name mapping can replace it.
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.
A block groups several sessions into one booking. Each session in a block syncs as its own Marketing Event. The block itself is not synced.
HubSpot’s Marketing Events index requires at least one registrant before showing an event. In HubSpot, open Marketing, then Events (under More if needed), then open the event by name. If it is missing, check both the course date and registration results in Cademy’s Sync Activity. Plan any test registration separately before creating it.
When comparing dates, check the displayed timezone and date format as well as the event name. Cademy sends event times in UTC. The default name uses the course date’s saved local time when available, with a UTC fallback for older date records. If the times appear different, give Support both displayed values and the course date.
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.
Select Save.
There are no registration fields to map. Cademy sends one of these participant statuses:
Registered
Attended
Cancelled
When a previously synced learner moves to another eligible date, Cademy cancels their participant status on the former event and sends their current status to the new event. If the new date cannot sync, the former event can be cancelled without a new participant entry. Check both events; Synced alone does not confirm the learner joined the intended new event.
A registration needs the learner's email address. Registrations without an email address are skipped.
A registration without a course date, including an on-demand registration, is not sent as a new participant entry. A registration on the block itself is also skipped. Registrations on the block’s sessions can sync. If a previously synced registration moves to a destination with no eligible event, the former participant entry can still be cancelled.
For an attended registration, Cademy sends Registered followed by Attended. Cancelled takes precedence over attendance. This integration does not send a separate Absent state: an uncancelled registration marked Absent is sent as Registered. Turning Contacts off does not prevent Cademy from updating participant status using the learner’s email address; leave it enabled if you need the learner’s mapped contact details sent too.
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 Contacts on the Mappings page, turn on Contacts Sync and select Save. Return to the Mappings list.
Open Messages on the Mappings page.
Turn on Messages Sync.
Select Save.
There are no message fields to map. Cademy fills the activity fields automatically.
The activity records available date, direction, sender, recipient, subject and summary information. Inbox messages include their text, shortened if necessary, and a conversation link when available. Learner replies are recorded as incoming activities. Automatic emails use their subject as the summary; the full stored email body is not copied. This writes an activity, not another email, and does not track delivery, opens or clicks.
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:
Before changing choices: In Map values, Save changes can immediately update the options of a shared Cademy custom dropdown or radio field. Adding or removing choices affects that field outside this mapping too. The mapping itself still needs Save at the top of the module page.
Select Apps, then HubSpot, and select your connection.
Open Mappings, choose the module and ensure its sync switch is enabled. Registrations and Messages have no fields to map.
Select Add Mapping.
Choose the Cademy Module.
Choose the Cademy Field.
Choose the HubSpot field on the right.
Where Map values is available, use it to pair Cademy choices with the HubSpot list values. Select Save changes in that dialog. Review the field-change warning above before adding or removing choices.
Complete or remove every unfinished row.
Select 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 source module supports it, Create new field… in the Cademy Field list opens a field creator. Saving there creates a Cademy field immediately; it is not held until the mapping page’s Save. You still need to complete and save 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 writes from that row; it does not erase the existing HubSpot value. Automatically managed matching properties, pipeline, stage and date status are separate.
Mapping changes apply to the next eligible sync, including a related-record sync or a Retry using current data. They do not update all historical records at once.
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
Agree a controlled test with the people responsible for both accounts. Test records and messages can affect reports, workflows and recipients. Use designated test data and an email address you control; agree any booking, payment or message actions before performing them. Do not use bulk changes to force a sync.
Create a test contact in Cademy with an email address you can recognise.
In HubSpot, open CRM, then Contacts, and search for the test email address. Open the matching contact and compare its mapped values.
In Cademy, select Apps, then 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.
For every module you test, check the intended HubSpot record type, record and linked records as well as Cademy’s status. Refresh or reopen Sync Activity to fetch the latest results. A connection test or a single Synced contact does not verify the other modules. If an outcome is unclear, stop the test and send Support the record, action, time and error.
Check Sync Activity
Select Apps, then HubSpot. Select a connection, then select Sync Activity.
This page shows up to 100 most recently updated sync records for this connection. Each row holds the latest result for a record, not a complete history of its attempts. All Statuses also includes Not attempted rows. The other filters are:
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.
Select Retry on that row.
Retry loads the selected record’s current Cademy data and current mappings. It can also send related contacts, organisations or dates needed by that record. It is not a historical import. After the retry, check the row’s status and Last error again, then the intended HubSpot record; the retry confirmation alone does not mean it synced successfully.
For Needs reconnect, update the connection using the steps below. These rows do not have a Retry button. Reconnecting does not itself resend old records or change every old row’s status. If a record still needs recovery afterwards, contact Support with the affected record and status instead of making unrelated edits to trigger it.
Some records, such as contacts without email addresses, are skipped before an attempt is recorded and do not appear here. A message whose contact cannot sync can retain a Not attempted or previous status. An empty list is not proof that all data was sent.
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, select Apps, then HubSpot.
Open the action menu on the affected connection.
Select Edit Connection.
Paste the current or replacement Service Key.
Select Test & Continue.
Check the Portal ID carefully.
Select Update Connection, then Finish.
Check the Portal ID against the existing connection before Update Connection. Cademy rejects a different portal when both IDs are available, but you must still confirm the intended account. Add a separate connection for another portal.
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 a key preserves existing mappings and module choices. It does not run a historical import or automatically retry all affected records. Check that the connection is Ready, inspect its saved mappings and follow the Sync Activity guidance for outstanding failures.
Disconnect a HubSpot account
Select Apps, then HubSpot.
Open the action menu on the connection.
Select Disconnect.
Confirm Disconnect.
The connection is marked Disconnected and is no longer selected for future automatic syncs. Existing HubSpot records remain. Disconnecting does not undo writes already sent or guarantee that an in-progress sync is cancelled.
You can reconnect later by choosing Edit Connection and entering a valid Service Key.
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.
Frequently asked questions
Why can I not open Apps or use HubSpot?
The Apps menu is shown only to System Admins. If you are a System Admin and cannot see Apps, it has been hidden from your menu: look under More. The ENTERPRISE and BETA labels do not confirm that HubSpot is enabled for your account. Contact Cademy Support if installation or access remains unavailable.
Why can I not create a Service Key?
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.
Why is a scope missing from the 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.
What if the connection test names a missing scope?
Add the named permission to the Service Key, then test it again. The next step depends on whether you have already saved a connection.
In HubSpot, open the Service Key, select Edit, add the named scope and save the change.
For a new connection that has not been saved, return to the connection setup in Cademy and select Test & Continue again. After a successful test, check the Portal ID, select Save Connection, then Finish.
For an existing connection, select Apps, then HubSpot, open its action menu and select Edit Connection. Enter the current key, select Test & Continue, check the Portal ID, then select Update Connection and Finish.
Why is Marketing Events unavailable?
Check that the Service Key has both of these scopes:
crm.objects.marketing_events.readcrm.objects.marketing_events.write
For a saved connection, use Edit Connection in Cademy to test the key again. If you have not saved it yet, return to its setup and select Test & Continue. If both scopes are present and access remains unavailable, contact Cademy Support with the exact message shown during the test.
Why are Organisations or Orders not syncing?
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
Check that the expected property is active, writable and has unique values. Do not delete or rename it as a troubleshooting experiment. Ask your HubSpot administrator and Cademy Support to agree a repair, then use Edit Connection to test and save again. Creating a property alone does not refresh Cademy’s saved matching settings.
Why did a contact or registration 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.
Why do Orders not sync after I enable them?
Open Orders under Mappings and check that a pipeline and all three stages are selected. Then select Save.
Why did a date sync without its learners?
Course Dates and Registrations have separate switches. Make sure both modules are on and saved. Also check that the learners have email addresses.
Why are messages missing from the contact 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.
Why did no historical records appear after connecting?
Connecting does not start a full historical import. Eligible changes and related-record syncs can send existing records later. Contact Support to plan historical data transfer; do not make bulk edits to force it.
What should I do when records show Needs reconnect?
Check the connection and update its Service Key through Edit Connection. Old Needs reconnect rows have no Retry button and are not automatically replayed by reconnecting. Give Support the remaining records and statuses if they need recovery.
Why did changing a mapping not update old HubSpot records?
Saving mappings does not resend history. The new settings apply on a later eligible sync or a Retry of a failed record, using current Cademy values. Related records can also sync as part of another record’s update.