HubSpot is Uni Compare's native-supported CRM. The integration uses a single access token issued by a Private App you create in your HubSpot portal.

HubSpot is fully supported by Uni Compare, and uses a Private App access token generated within your HubSpot portal.

What we need from you

A Private App access token from your HubSpot portal, scoped to Contacts read and write only.
Your HubSpot Account ID (also called Hub ID). This is a short numeric identifier.
The name and email of a HubSpot Super Admin we should contact when the token approaches expiry. HubSpot tokens are recommended for rotation every six months; we will request a fresh token a couple of weeks before that deadline.
If you have a HubSpot Sandbox account (Enterprise plans include a Standard Sandbox), a separate token and Account ID for the sandbox. We use it for the pre-go-live test.

Where in HubSpot to set it up

Step 1. Log in as a HubSpot Super Admin

In HubSpot, log in as a Super Admin. Make sure you are in your standard HubSpot portal, not a Developer Account because Private Apps cannot be created inside Developer Accounts. The account selector is in the top-right corner.

Step 2. Navigate to Private Apps

Go to Settings (the cog icon top-right) → Integrations. In the left sidebar, look for one of the following in this order: (a) "Private Apps": the direct path; (b) "Legacy Apps": in many 2026 portals HubSpot has renamed the page, click "Legacy Apps", then "Create Legacy App", then choose "Private App" when prompted; (c) if neither is visible, check the FAQ below about plan and role restrictions.

Step 3. Create the Private App

Click "Create a private app" (or "Create Legacy App" → Private). Give it a name like "Uni Compare lead delivery".

Step 4. Set the OAuth scopes

Open the "Scopes" tab. Tick exactly these three scopes, leave everything else unticked, and save:

crm.schemas.contacts.read
crm.objects.contacts.read
crm.objects.contacts.write

Step 5. Generate the access token

Click "Create app", confirm any consent dialog, and open the Auth tab and copy the access token.

Step 6. Find your Account ID

Click your account name in the top-right corner (next to the profile avatar) to open the account dropdown. Under the "Account" section, you will see your account name and below it a numeric identifier. That number is your HubSpot Account ID (also called Hub ID). Note it down. You will need to send it alongside the token.

Verify before sending

Before sending the token and Account ID, confirm the following:

Token format. The token should look like pat-eu1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx for EU-region portals, or pat-na1-xxxxxxxx-... for North America. If your token starts with anything else (like a long alphanumeric string with no pat- prefix), you have most likely copied a Developer API Key or a Public App Client Secret instead. If this is the case, please go back and copy from the Private App access-token page.
Scopes. Re-open the app in HubSpot and confirm the Scopes tab shows exactly these three, nothing more, nothing less:
- crm.schemas.contacts.read
- crm.objects.contacts.read
- crm.objects.contacts.write
Account ID copied correctly. The Account ID is the numeric identifier you noted in Step 6. Make sure you have it on hand to send alongside the token.
Channel. Generate a one-time encrypted link using our secrets page with the token and Account ID, then email the link to your Uni Compare contact.

Important: Never paste the token into a web chat, plain email, or any unencrypted attachment.

Field mapping

We create Contact records in HubSpot, deduplicated by email. If a contact with the same email already exists, we update it; otherwise we create a new one.

We pass each lead to you with the following fields, mapped onto built-in HubSpot contact properties where possible and at times onto custom properties otherwise (must be agreed with you at onboarding for the exact custom-property names).

If your portal already has properties for some of these, please share these with the Uni Compare team so we can map onto those:

First name and last name → built-in firstname, lastname
Email → built-in email
Phone (where given) → built-in phone
Postcode → built-in zip
Address (where given) → built-in address
Study Level (undergraduate or postgraduate) → custom property
Start Year → custom property
Subject Area (where given) → custom property
Free-text enquiry message (where given) → custom property
Lead type → custom property
Marketing consent flag → custom boolean property (you choose how to use it in subscription preferences or workflows)
Uni Compare lead identifier → custom property (for traceability)

Frequently asked questions

HubSpot calls this "Legacy Apps" now. Is it being deprecated?

No. In 2025–2026 HubSpot consolidated all app types (private apps, public apps, marketplace apps) under one "Legacy Apps" page as part of their new Developer Platform rollout. The word "Legacy" here is a HubSpot product-naming choice, not a deprecation signal. As of mid-2026, HubSpot has officially confirmed that legacy private apps are fully supported and actively maintained, with no announced sunset date. The HubSpot developer documentation explicitly recommends private apps for API-only use cases like ours. The new Projects-based developer platform is aimed at apps with UI extensions and marketplace listings. That's a different use case from a simple data integration.

I cannot find "Private Apps" or "Legacy Apps" in my settings.

Three common reasons. First: you may be logged into a HubSpot Developer Account rather than a standard HubSpot portal. Developer Accounts cannot create private apps. Switch portals using the account selector in the top-right corner. Second: your HubSpot plan may not include API access. Most paid plans (Starter and above) do, but some legacy Free accounts do not. Third: your user role may not have the necessary permissions, as Private App creation requires Super Admin permissions. If none of those apply, contact your HubSpot account manager or open the support chat, and we will help diagnose.

Should we use HubSpot's new "Service Keys" instead?

Not yet. HubSpot introduced Service Keys in 2026 as the eventual replacement for private-app-style API credentials. As of mid-2026 Service Keys are in public beta. They are not generally available for production use, behaviour may still change, and webhooks are not yet supported. For a production integration like Uni Compare, we recommend you continue with Private App access tokens until Service Keys reach general availability and we have updated our integration to support them. We will communicate via the support chat when that happens.

Why not use a HubSpot OAuth app (Public App) instead of a Private App?

Public Apps (the OAuth model) are designed for marketplace integrations distributed to many HubSpot customers. For a one-to-one integration like this, Private Apps are the recommended path. (Here that means Uni Compare delivering leads into your specific portal.) They are simpler, give you direct control over scopes and rotation, do not require an install-flow handshake, and isolate any credential issue to your portal only.

What if we want to revoke the token?

Go to the same Private Apps page (or Legacy Apps page on newer portals) and either delete the app entirely or rotate the token. The integration stops working immediately. Tell us via the support chat so we are not surprised, and we can rotate without service interruption.

Why these specific three scopes?

crm.objects.contacts.write lets the integration create new contacts and update existing ones. This is the core action. crm.objects.contacts.read lets the integration check whether a contact already exists before creating, to avoid duplicates. crm.schemas.contacts.read lets the integration read the schema of your contact properties so the field mapping works correctly with any custom properties you have configured. These three scopes together follow the principle of least privilege. Anything broader is unnecessary and increases your exposure if the token were ever leaked.

Useful links

Private Apps overview — HubSpot's reference for what Private Apps are, how they work, and how tokens are managed.
Available scopes reference — the full list of all HubSpot OAuth scopes, useful if your security team wants to verify that the three scopes we ask for are minimal.

HubSpot Integration