You've built the app, the OAuth flow works, and you're ready to submit. Then the review comes back asking you to remove six scopes and rewrite your setup guide.
We've listed two apps in the HubSpot Marketplace, Koalify - Merge & Deduplicate and Koalify - Email Validation, and both were approved quickly. We recently joined Jana from HubSpot's Ecosystem Quality team, the people who review every Marketplace listing, for a conversation on HubSpot's developer channel. Jonas and Tim (Koalify's co-founders) shared what worked, and Jana explained where most first submissions fall short. You can watch the full video below.
HubSpot admins don't want another platform to log into. That's why Koalify uses HubSpot properties, CRM cards, workflow actions and the app settings page. There's no separate interface to learn. Admins judge an app by how little it asks of them, and an app that feels like part of HubSpot needs less training and less support.
Tim's advice is to start with only the OAuth scope and add others when a feature genuinely needs them. Don't request anything "just in case."
Every scope must link to at least one feature in your listing. HubSpot also checks your API activity to confirm each scope is used. Before you submit, generate the sample install URL from your project's distribution settings. It shows you exactly which permissions users will be asked to grant.
What stood out to Jana was that our listing showed the integration itself. A strong listing includes:
1. Weak setup documentation. Linking to your homepage isn't a setup guide. Reviewers want written, step-by-step instructions from install to first use.
2. Shared data table errors. Every scope you request should map to a HubSpot object in the table.
3. Unused scopes. If there's no API activity to justify a scope, you'll be asked to remove it. That includes scopes for features you haven't built yet.
Get unaffiliated beta users to install the app and use it in their own portals. Their usage generates the API activity reviewers need, and it gets you the active installs required to apply (check the listing requirements for the current number). It's also a useful test of whether anyone actually wants the app.
Solve one small problem exactly. A focused app is easier to build, review and understand, and you can add features once people are using it.
Learn More & Stay Connected
Get started with HubSpot Development 👉 https://developers.hubspot.com/