What This Update Actually Is
HubSpot has launched the Lead Scoring Public API in public beta. It exposes a set of versioned REST endpoints under /marketing/lead-scoring/2026-09-beta/scores on developers.hubspot.com.
Before this, lead scoring lived entirely inside the HubSpot UI. You had to log in, click through the scoring editor, and save changes manually. Every rule, every threshold, every group config was portal-bound.
Now those configurations are addressable via code. The API covers the full lifecycle of a score: draft, publish, update, clone, deactivate, and delete. It also lets you read computed score values from CRM records using the existing objects API, pulling from each score's output property.
The scoring model supports two group categories: fit (who the lead is) and intent (what the lead is doing). You can combine both in a single score, set a max score per group, and map the output to any property on a contact or company record.
Why HubSpot Shipped This
We've seen this problem repeatedly across portals we audit. A company has solid lead scoring logic inside HubSpot, but their sales team also uses an external CRM layer, a BI tool, or a custom-built ops platform. Getting scores in or out of HubSpot required workarounds: property syncs, Zapier hacks, or manual exports.
The internal frustration is real. RevOps humans who maintain scoring models in HubSpot know how painful it is to update criteria across a growing portal with no programmatic way to version, test, or deploy changes. One misconfigured rule affects every contact. There's no staging environment inside the UI.
HubSpot shipped this to close that gap. Integrators, agency developers, and RevOps engineers can now manage scoring configurations as part of a real deployment pipeline, not just a manual portal task.
How to Use It Step by Step
- Authenticate your app. You'll need a private app token or OAuth with the appropriate lead scoring scopes. Check the scopes section of the Lead Scoring API beta guide on developers.hubspot.com.
- Create a draft score. POST to /marketing/lead-scoring/2026-09-beta/scores with your objectTypeId (0-1 for contacts, 0-2 for companies), a name, your allowedGroupTypes (fit, intent, or both), and your groupConfigs array. Set outputProperty to the HubSpot property where the score value should land. A 201 response confirms the draft was created.
- Add or refine rule configurations. PUT to /scores/{scoreId}/draft to upsert the full draft. Each ruleConfiguration inside a group needs a configuration object with a type (such as PROPERTY_RULE), a propertyName, an operator, and a value. Set scalingFactor and maximumValue to control how much each rule contributes to the group total. This is a full overwrite, so include all rules every time.
- Publish the draft. POST to /scores/{scoreId}/draft/publish. For a new score, this activates it and triggers an evaluation of all matching records. For an existing score, it re-evaluates records against the updated criteria immediately.
- Read score values on records. Use the standard HubSpot Objects API to retrieve the outputProperty value from any contact or company record. If you set outputProperty to hubspot_lead_score, that property holds the live computed value.
- List and audit existing scores. GET /marketing/lead-scoring/2026-09-beta/scores returns a paginated list of all score summaries, including each score's id, name, scoreType, and lastConfigurationChangeTimestamp. Use the limit and after query parameters to paginate.
- Clone, reset, or deactivate as needed. POST to /scores/{scoreId}/clone to duplicate a score (useful for testing variants). POST to /scores/{scoreId}/draft/reset to discard unpublished changes and return to the live config. POST to /scores/{scoreId}/deactivate to turn off a score while preserving its groupConfigs for future use.
What It Touches in Your HubSpot Strategy
This update ripples into more of your tech stack than it might first appear. Here's where to think carefully.
CRM properties and record data. Score values land on contact or company records as property values. That means every workflow, list, view, report, and integration that reads those properties is now indirectly affected by how you configure scores via the API. If you change the outputProperty name, downstream automations can break.
Key Takeaway
Always keep your outputProperty name stable across API updates. Changing it mid-deployment will silently break any workflow, list, or integration that references the old property name.
Workflows and automation. Workflows that trigger on score thresholds (for example, enrolling a contact when hubspot_lead_score is greater than 75) will respond immediately when you publish a new scoring config. Plan your publish timing carefully. A re-evaluation runs on all records the moment you publish, which means workflow enrollments can spike.
External analytics and BI tools. If your team pushes HubSpot contact data into a BI platform like Looker, Tableau, or a data warehouse, score values are now a first-class programmatic data point. You can read them via the objects API on a schedule, or sync them as part of your ETL pipeline.
Partner integrations and marketplace apps. HubSpot Connect partners can now build deeper integrations that read or write scoring logic. If you use a third-party intent data platform, an enrichment tool, or a sales intelligence tool, expect those vendors to start exposing score-write capabilities as a native feature.
This update pairs well with other API-forward releases HubSpot has shipped recently. If you're building a programmatic RevOps stack, the Sales Templates Public API and the Contracts API for HubSpot are part of the same broader pattern: HubSpot is systematically opening its core commercial tools to programmatic control.
Key Takeaway
Lead scoring rules are now deployable artifacts, not just UI settings. Treat them like code: version them, test changes in a clone, and publish on a schedule that accounts for workflow enrollment spikes.
If you want to understand the bigger picture of where HubSpot's programmatic capabilities are heading, our HubSpot Agentic Platform pillar maps out the full trajectory, including where API-driven configuration fits into the agentic stack.
Who Should Care Most
Not every HubSpot admin needs to touch this API. But certain humans will find it immediately valuable.
- RevOps engineers and HubSpot developers who maintain scoring models across multiple portals or business units. The clone endpoint alone saves hours of manual recreation.
- HubSpot Solutions Partners and agencies who onboard new clients and need to deploy standardized scoring templates programmatically rather than rebuilding them by hand in each portal.
- Marketing ops leaders at companies using external intent data tools. If your intent signals live outside HubSpot (Bombora, G2, Clearbit, or similar), the API is how you eventually close the loop between those signals and HubSpot scoring logic.
- Growing B2B companies on Sales Hub or Marketing Hub Professional and Enterprise who have outgrown manual scoring updates and want to treat their lead qualification logic as a versioned, auditable system.
If you're still in starter-tier HubSpot, this one isn't for you yet. The API requires Professional or Enterprise on either Sales Hub or Marketing Hub.
George's Take
What excites me most here isn't the API itself, it's what it signals. HubSpot is moving from a portal you log into and click around, toward a platform you deploy against. Lead scoring has always been one of those features that sounds great in demos but becomes a mess in practice, because the rules drift, the criteria get stale, and nobody can remember why a particular threshold was set six months ago. Making it programmable means humans who care about data quality can actually govern it. You can version your scoring logic, review changes in a pull request, and deploy with confidence instead of hoping nobody changed something in the UI overnight.
“Lead scoring just became a deployable artifact. That changes how serious RevOps teams should think about governance, versioning, and what it means to actually own your data.”
If your portal's lead scoring is already solid and you're curious how it connects to the broader RevOps picture, start with our HubSpot Merge Rules update. Clean data is the prerequisite for accurate scoring, and those two things work together.
Ready to build a scoring system your whole revenue team can trust? Let's map it out together. Book a strategy call with the Sidekick team and we'll show you exactly how to structure scoring logic that scales with your business, not against it.
Frequently Asked Questions
What is the HubSpot Lead Scoring Public API?
The HubSpot Lead Scoring Public API is a set of versioned REST endpoints that let developers create, read, update, delete, publish, clone, and deactivate lead scoring configurations programmatically. It also allows you to read computed score values from contact and company records via the HubSpot Objects API. It's currently in public beta.
Who can access the Lead Scoring API in HubSpot?
The Lead Scoring API is available to portals on Sales Hub Professional, Sales Hub Enterprise, Marketing Hub Professional, and Marketing Hub Enterprise. Starter-tier portals don't have access. You'll need a private app token or OAuth credentials with the correct lead scoring scopes to authenticate.
How do I publish a lead scoring configuration using the API?
First, create a draft by POST-ing to /marketing/lead-scoring/2026-09-beta/scores with your objectTypeId, name, groupConfigs, and outputConfiguration. Then publish it by POST-ing to /scores/{scoreId}/draft/publish. Publishing triggers an immediate re-evaluation of all matching CRM records against the new criteria.
Can I clone an existing lead score configuration via the API?
Yes. POST to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/clone with a scoreName in the request body. If the source score has an active draft, the clone is built from the draft. If not, it clones the published configuration. The new score is created with a status of draft and must be published separately.
Will publishing a new scoring configuration affect my existing HubSpot workflows?
Yes, immediately. When you publish or update a score, HubSpot re-evaluates all records against the new criteria right away. Any workflow that triggers on a score property threshold can enroll or unenroll contacts in bulk. Plan publish timing carefully and monitor workflow enrollment activity after any scoring change.
How do I read a contact's current lead score value using the API?
Use the standard HubSpot Objects API to retrieve the contact or company record and request the score's outputProperty field, for example hubspot_lead_score. The value returned is the most recently computed score. You can't read historical score changes directly through the lead scoring endpoints; use the outputProperty on the record instead.
