HubSpot setup guide

Before you start

• A Peerfold workspace. Every plan opens with a seven-day free trial, every feature switched on, and no card.
• A HubSpot account where you may install apps and approve the permissions one asks for. A portal feeds one Peerfold workspace at a time.
• For the page modules and the course-site theme, a Peerfold plan of Professional or above, and Design Manager access in HubSpot.

Nothing below is destructive. Connecting provisions properties, reads what is already there, and leaves anything it finds alone.

Connect your portal

There are two ways in, and they finish in the same place.

1. Starting in Peerfold. Open Settings, then HubSpot, and press Connect HubSpot. You sign in to HubSpot, approve the access, and land back on that page with the portal attached to the workspace you were in.
2. Starting in HubSpot. If you install the Peerfold app from HubSpot first, HubSpot has no way of knowing which Peerfold workspace the portal belongs to. Come back to Settings, then HubSpot, where a card offers to finish connecting and names the workspace it will use. Press Connect to this workspace and the sync starts.
3. If you run more than one workspace. Switch to the workspace you want the portal on before you press that button. The card names the workspace it will use, and it says so when that workspace already holds a different portal, because attaching the new one replaces it.

A portal already connected somewhere else is refused by name rather than moved quietly. Disconnect it in the other workspace first. The finish-connecting card expires after half an hour; if you left it sitting, press Connect HubSpot instead.

What Peerfold asks permission for

The consent screen HubSpot shows you lists the app's scopes. These are the ones the sync uses, and why.

• Contacts, read and write. A learner is a contact, so Peerfold reads to match by email and writes the learning properties, the timeline notes and the profile changes a learner makes.
• The Courses object, read and write. This holds both the catalog record for a course and the per-learner record carrying somebody's status.
• Custom objects and schemas. The properties and object types Peerfold writes to are provisioned once, at connect time.
• Lists, read only. This one is optional, and it powers access rules that let a HubSpot list decide who may open a course.
• Deals, read and write. Optional as well, and it powers membership deals and the partner program's deal sync.

A portal that declines an optional permission still connects, and the feature behind it stays off until an administrator reconnects and grants it. Nothing is made required for a feature most workspaces never switch on.

Check that it provisioned cleanly

1. Read the provisioner report. Settings, then HubSpot, shows three counts after a connect: created, existing, and errors. Existing is the normal case. It means the property was already in your portal and was left exactly as it was.
2. Fix errors by reprovisioning. An error means something was not created, usually a permission in the portal. Press Reprovision to run it again. It is safe to repeat as often as you like.
3. Reconnect when the scopes change. Reconnect runs authorization again. Use it after an administrator grants an optional permission, such as list access, so the new scope reaches the stored connection.

Watch the sync

Settings, then Sync, is the queue that drains course, enrollment and progress writes into your portal. Three counts summarize it: pending, dead, and done today. The table under them lists recent writes with the kind of write, its status, how many attempts it has had, the last error, and when it will next be tried.

A write that fails is retried with a growing delay. One that keeps failing is marked dead, which is the queue saying a person should look at it. The error text is the one HubSpot returned, so it usually names the problem outright: a missing property, a permission, a rate limit. Fix the cause, then retry one row to test it, then retry the rest.

Connecting later rather than sooner costs you nothing that is already recorded. Everything learners do after the connect flows to your portal; activity from before it stays in Peerfold and is not backfilled.

Put the courses on your HubSpot site

Your learners can read the courses on a Peerfold portal at your own domain, or on the HubSpot website you already publish. The second one is two downloads, and neither is part of the app.

• Peerfold modules: nineteen drag-and-drop modules that appear in the page editor of whatever theme your site runs today. You choose which pages get them and where, and nothing about your site changes until you drag one in.
• The HubLMS theme: a whole course-site theme with its own templates, catalog, course player and navigation. It extends the Omega theme, which has to be in the portal already.

You get both from Settings, then HubSpot theme, inside Peerfold, with your workspace address and publishable key already written into the files. One step is easy to miss and has no error message: add your site's origin to the allowed list on the same screen, or every module renders empty.

Connect a Breeze agent

Peerfold runs a remote MCP server, so an AI agent with a connection can work your live workspace: look up who finished onboarding, enroll a deal's contacts in a certification course, list who is overdue. This is separate from the CRM sync. Sync copies records into HubSpot; an agent calls tools here, live.

It needs a Peerfold plan of Professional or above, and a workspace administrator to approve it. Authorization is OAuth 2.1 with PKCE, the grant is scoped to one workspace and can reach no other, and the entitlement is checked again on every request rather than once at consent. Every write is audit-logged and reaches the CRM through the same queue as everything else. Publishing a course is an explicit tool and never a side effect.

The server publishes 256 tools. Each one declares whether it reads, writes or deletes, and an agent client reads that to decide when to ask you first.

Connecting the server is not enough on its own. The agent's prompt has to name the tools and say when to reach for them, or it answers from what it already knows with a live connection sitting unused. Paste this into the agent's instructions and adjust it to taste:

You can use Peerfold's training tools for questions about courses,
learners and progress.

- For "who finished / who is behind / how is training going", use
  list_learners, list_overdue, get_learner_progress and
  get_organization_progress. These are read-only, so use them freely.
- To enroll someone, use enroll_learner (by email). Confirm with the
  human before enrolling, and never unenroll without being asked.
- Answer from tool results, not from memory. If a tool refuses, say
  why rather than retrying.

Revoking is one press, at Settings, then Developers, then Connected AI assistants. It kills every token that grant ever minted, refresh tokens included.

Deleting a contact, and removing the app

Nothing HubSpot sends ever erases data in Peerfold on its own. When a contact is deleted under a privacy request, Peerfold unlinks that learner from the sync at once and cancels the writes queued for them, because writing course records onto a purged contact would recreate what HubSpot just destroyed. It then files a request for a workspace administrator to review, and confirming that request is the only path to an erasure. An ordinary contact delete unlinks and does nothing else, since HubSpot can restore one for ninety days. A merge re-points the link at the surviving record so the sync carries on.

Erasing a learner in Peerfold deletes what can go and redacts what has to survive. A certificate keeps its serial number and its public check while the name comes off it, and an audit record keeps its integrity while the actor becomes an opaque token. A suppression marker then stops the sync from recreating that person.

Uninstalling the app in HubSpot stops the writes. The stored token stops working and queued writes stop landing. No learner-facing part of Peerfold reads the CRM for anything it shows on a screen, so the portal, the courses and the certificates all keep working through an uninstall.

How long Peerfold keeps each category of data, and what deleting a workspace removes, is written out on the data retention page.