CRM·developers.hubspot.com·researched guide, 2026-10-30

HubSpot (CRM API)

Building a HubSpot OAuth app is quick (under an hour with the CLI) and free, but it must be a Projects-based app now: legacy public app creation was switched off in May-June 2026. A marketplace-distribution app is capped at 25 installs until it is listed on the HubSpot Marketplace, and listing needs at least three active installs in production accounts not affiliated with you, plus a manual review (first response within 10 business days, up to 60 days overall).

Difficulty

moderate

First token

30-60 min

Real users

Same day (25 installs)

Cost

Free

Review: None for the first 25 installs. Beyond 25: Marketplace listing review by HubSpot's Ecosystem Quality team. Certification is optional (60+ active installs, 6 months listed).

Timing: Immediate for up to 25 clinics; 3-10 weeks to lift the cap via Marketplace listing (time to reach 3 active unaffiliated installs + 10 business days first review, up to 60 days).

Verdict evidence sourceds1 s2 s3

Before you start

Iskaria readiness: 3 of 4 profile items in place

edit profile

for buildHubSpot developer account (free) and HubSpot CLI v7.6.0+ authenticated with hs account authsourceds4
for buildHTTPS OAuth redirect URL(s) declared in app-hsmeta.json✓ Iskaria has itsourceds4
for launchAt least three active, unique installs in HubSpot production accounts unaffiliated with Iskaria (successful API activity in the past 30 days)sourceds2
for launchLive Terms of Service and Privacy Policy URLs✓ Iskaria has itsourceds2
for launchPublic setup documentation specific to the HubSpot integration (HubSpot provides a template). Not in the profile: MISSING.sourceds2
for launchAt least one support contact method and live support resource URL✓ Iskaria has itsourceds2
for launchApp logo / listing images. Profile logo.square512Png is null: MISSING.✗ missing in profileinferred

Test mode:availablesourceds1 s4

Developer test accounts let you install and test in isolation. Unlisted marketplace-distribution apps: max 25 installs. Private-distribution OAuth apps: max 10 customer accounts (100 for Solution Partners).

Who does what

Agentcan do for you

Install the CLI, scaffold the project and write app-hsmeta.json
Run hs project upload and fix build errors
Implement the OAuth code exchange, token refresh and CRM contact/deal sync
Draft the setup documentation page and the Marketplace listing text
Check that every requested scope is actually used

Youmust take over

Create the developer account and paste the personal access key for hs account auth
Approve installs in the test account and in each clinic's HubSpot
Recruit three unaffiliated clinic accounts to use it actively
Accept the App Partner Program Agreement and submit the listing

Steps

Buildcreate the app and credentials

1Create a developer account and a test accountYou10 minsourceds4
Sign up for a free HubSpot developer account. In it, Development > Test accounts > Create developer test account, for isolated installs.
https://developers.hubspot.com
Company name Iskaria
Email ibrahim@iskaria.com
2Install and authenticate the HubSpot CLIAgent drafts, you submit5 minsourceds4
npm install -g @hubspot/cli (v7.6.0 or later), then hs account auth: the human pastes a personal access key from the browser.
3Scaffold a Projects-based appAgent10 minsourceds4 s5 s6
hs project create with the app boilerplate. Choose marketplace distribution (multi-tenant; not restricted to specific accounts) and OAuth auth. Do not build a legacy public app: creation was disabled 26 May 2026 (new accounts) / 23 June 2026 (existing accounts). Target the current platform version (2026.09); 2025.2 must migrate by March 2027.

4Configure app-hsmeta.json: uid, redirect URLs, scopesAgent10 minsourceds4 s7

Set a unique uid, config.distribution = "marketplace", config.auth.type = "oauth", redirectUrls = ["https://app.iskaria.com/api/oauth/hubspot/callback", "http://localhost:3000/api/oauth/hubspot/callback"], requiredScopes = crm.objects.contacts.read/write and crm.objects.deals.read/write (oauth is added automatically). Put anything not always needed in optionalScopes or conditionallyRequiredScopes.

redirectUrls	["https://app.iskaria.com/api/oauth/{provider}/callback","http://localhost:3000/api/oauth/{provider}/callback"]Localhost redirect acceptance not verified
name / description	Iskaria is a multi-clinic operations console with an AI assistant. Clinic staff connect their business accounts so the assistant can answer patient messages, track leads and report on marketing performance.

5Upload and build the projectAgent5 minsourceds4
hs project upload; each upload triggers a build. Copy the client ID and secret from the app's Auth page in the developer account.

Testworks for you and test users

6Install into a test account and get a tokenAgent drafts, you submit15-30 minsourceds6
Open the install URL, choose the developer test account, approve. Exchange the code for access + refresh tokens and call the CRM contacts and deals endpoints using date-based API versions (not v1-v4, which lose certification after September 2027).

Launchreview and approval for real users

7Roll out to the first clinics (up to 25)Youongoingsourceds1 s2
Clinics install via the OAuth link. Up to 25 installs need no review. Get at least three clinics, outside Iskaria, actively syncing (API calls in the last 30 days) to qualify for listing.

8Submit a Marketplace listing (to lift the 25-install cap)Agent drafts, you submit2-3 h hands-onsourceds2

From the developer account create the listing: integration-specific description, setup docs URL, ToS/privacy URLs, support contact, scopes matching what the app actually uses, agree to the App Partner Program Agreement. Follow HubSpot branding rules (capital S in HubSpot; no 'Hub'/'HubSpot' in the app name or logo). Initial review within 10 business days; whole process up to 60 days.

Privacy policy URL	https://iskaria.com/privacy
Terms of service URL	https://iskaria.com/terms
Support URL	https://iskaria.com/support
Support email	ibrahim@iskaria.com
Setup documentation URL	MISSING in profile

9Optional: apply for app certificationAgent drafts, you submithalf a daysourceds3
Eligible after 6 months listed with 60+ active unique installs. Reviewed for security, privacy, reliability, performance, usability, accessibility and value; response within 10 business days.

Scopes an agent typically needs

Scope	Used for	Review tier	Evidence
crm.objects.contacts.read	Look up existing patients/leads before creating duplicates Available to all accounts.	basic	sourceds7
crm.objects.contacts.write	Create and update leads from WhatsApp/Instagram enquiries	basic	sourceds7
crm.objects.deals.read	Read booking/deal stages for reporting	basic	sourceds7
crm.objects.deals.write	Create deals for bookings and move them through stages	basic	sourceds7
oauth	Base OAuth scope Added by default to all apps; do not list it yourself.	basic	sourceds7

What can slow you down or block approval

can block launch25-install cap until listedsourceds1

Since 22 Sep 2025, marketplace-distribution apps created on or migrated to the Projects platform are capped at 25 installs until approved for the Marketplace. Legacy public apps with more than 25 installs get the cap enforced when migrated.

Workaround: Start the listing as soon as three clinics are actively using it; for a handful of clinics, private distribution (10 accounts) also works.

slows you downListing needs 3 active installs from unaffiliated production accountssourceds2 s8

Active installs count unique production accounts unaffiliated with your organisation with API/webhook activity in the past 30 days. Your own test or sandbox accounts do not count, despite some blogs saying they do.

Workaround: Onboard three real clinic HubSpot accounts first (Dr. Namshi's, Dr. Jefna's if they use HubSpot).

slows you downUnused or unneeded scopes get the listing rejectedsourceds2

The app must use every scope it requests; unused ones must be removed, and scopes only some users need must be conditionally required or optional.

Workaround: Keep to the four CRM scopes above; exercise each in normal operation.

infoPlatform churn: 2025.2 and legacy apps go unsupportedsourceds6

Legacy public apps went unsupported 15 Sep 2026 (enforcement Sep 2027; delisting risk). Projects 2025.2 apps must migrate to 2026.09 by March 2027. Apps using v1-v4 APIs after Sep 2027 lose certification; use date-based versioning.

Workaround: Build on 2026.09 with date-based API versions from the start.

infoRestricted industriesinferreds2

Listed apps must not cater to or be exclusive to customers in HubSpot's restricted industries. Whether healthcare clinics fall under any restriction was not verified; HubSpot's HIPAA stance matters for patient data.

What we checked

Claim	How	Result
Unlisted apps are limited to 25 installs Applies to Projects-based marketplace-distribution apps since 22 Sep 2025; private distribution is 10 accounts (100 for Solution Partners).	Fetched the HubSpot changelog post on install limits	confirmed
You can choose between legacy public apps and Projects-based apps Legacy public app creation disabled 26 May 2026 (new accounts) and 23 June 2026 (existing); current platform version is 2026.09, and 2025.2 must migrate by March 2027.	Search + legacy-public-app-creation-sunset changelog and legacy apps overview	corrected
Sandbox/test installs count toward the 3-install listing minimum (appnigma blog) Official: unique production accounts unaffiliated with your organisation, active in the past 30 days.	Fetched the official listing requirements page	corrected
Listing review takes about 10 business days Initial review within 10 business days; full process up to 60 days.	Listing requirements page and certification requirements page	confirmed
Certification needs 60 active installs and 6 months listed	Fetched certification requirements page	confirmed
Marketplace-distribution apps on the new platform are capped at 25 installs until listed; private distribution 10 accounts (100 for Solution Partners) Applies from 22 Sep 2025 to apps created on or migrated to 2025.2+; legacy apps with >25 installs get the cap on migration.	Independent check: re-fetched the HubSpot changelog 'New Marketplace Distribution App Install Limits' (s1) and the Authentication overview on 2026-10-30	confirmed
Listing needs 3 active installs from unaffiliated production accounts (30-day activity); first review within 10 business days The 60-day figure is the maximum for the whole feedback process, counted from when feedback is shared, not from submission.	Independent check: fetched the live App listing requirements page (s9) on 2026-10-30	confirmed
Legacy public apps unsupported 15 Sep 2026 (enforcement Sep 2027); 2025.2 apps migrate to 2026.09 by March 2027; v1-v4 APIs lose certification after Sep 2027	Independent check: re-fetched the HubSpot changelog (s6) on 2026-10-30	confirmed
OAuth endpoint behaviour (discovery metadata, PKCE, dynamic registration, unknown-client handling) HubSpot publishes RFC 8414 metadata: PKCE S256 only, code flow only, no dynamic client registration, no OIDC. Unknown client_id on /oauth/authorize returns HTTP 200 with the OAuth UI page (error rendered client-side).	Endpoint probe: node scripts/probe.ts on 2026-10-30	confirmed

Still uncertain

Exact string for private distribution in app-hsmeta.json was not shown in the doc example (only "marketplace").
Whether http://localhost redirect URLs are accepted by the Projects platform was not verified.
Real review wait beyond HubSpot's stated 10 business days / 60 days is anecdotal.
Whether an unlisted app shows an extra warning at install is from a third-party write-up only (unified.to), not verified.
Listing image/logo specs and whether a demo video is currently required were not confirmed; the English requirements page as summarised did not mention them.
Restricted-industry implications for healthcare clinics not checked.

Sources

s1
New Marketplace Distribution App Install Limits (changelog) · official-docs · accessed 2026-10-30
“apps that are created or migrated to version 2025.2 are capped at 25 installs”
s2
App listing requirements in the HubSpot Marketplace · provider-policy · accessed 2026-10-30
“Installs: your app must have at least three active, unique installs.”
s3
App certification requirements · provider-policy · accessed 2026-10-30
“Your app must have at least 60 active, unique installs to qualify for and retain certification.”
s4
Create an app (developer platform) · official-docs · accessed 2026-10-30
“Make sure you're using v7.6.0 of the HubSpot CLI before proceeding.”
s5
Legacy Public App Creation Sunset (changelog) · official-docs · accessed 2026-10-30
“Beginning May 26, 2026, the ability to create new legacy public apps via the Developer Platform UI will be permanently disabled.”
s6
Legacy APIs and Apps: What's Going Unsupported and When (changelog) · official-docs · accessed 2026-10-30
“Apps on the Projects 2025.2 framework, or older, need to migrate to the current version (2026.09) by March 2027.”
s7
Scopes · official-docs · accessed 2026-10-30
“Basic scope required for OAuth. This scope is added by default to all apps.”
s8
HubSpot App Marketplace: Listing Requirements for ISVs (appnigma) · community · accessed 2026-10-30
“Sandboxes count, real customers count, beta installs count.”
s9
App listing requirements in the HubSpot Marketplace · official-docs · accessed 2026-10-30
“your app must have at least three active, unique installs ... unique HubSpot production accounts, unaffiliated with your organization ... within the past 30 days.”
s10
Endpoint probe, 2026-10-30 · our-test · accessed 2026-10-30
“code_challenge_methods_supported: [S256]; response_types: [code]; no registration_endpoint; no openid-configuration (404)”

Something wrong or outdated? Re-run the agent for HubSpot (CRM API)