Lead Scoring API (BETA)

Supported products

Scope requirements

Use the Lead Scoring API to draft, publish, and manage lead score configurations (i.e. rules, criteria). Once a score is published, you can retrieve records’ current scores or view score history over time. Learn more about lead scores in HubSpot.

Create a lead score

To create a new score configuration, make a POST request to /marketing/lead-scoring/2026-09-beta/scores. Include the following in the request body:

Parameter	Type	Description
`objectTypeId`	String	The ID of the CRM object to score: `0-1` for contacts or `0-2` for companies.
`name`	String	The score’s name.
`allowedGroupTypes`	Array	The scoring types permitted in this score’s logic. Accepted values: `fit`, `intent`. Include both values to allow groups with both scoring types (i.e. a combined score).
`groupConfigs`	Array	The rule groups that make up the score’s criteria. Each group contains a `groupCategory` (`fit` or `intent`), a `groupName`, and a `ruleConfigurations` array that sets a group’s rules.
`maxScore`	Number	The maximum total score value. Default value is `100` for each scoring type.
`outputConfiguration`	Object	Information about how record score values are stored and synced. Include the following fields: `outputProperty` (the name of the property where the score values are stored on records) and `syncEnabled` (whether to sync the output property value after scoring: `true` or `false`).

The request creates a new score with an initial draft configuration. Drafts must be published to become active scores that evaluate records.

{
  "objectTypeId": "0-1",
  "name": "New Lead Score",
  "allowedGroupTypes": [
    "fit",
    "intent"
  ],
  "groupConfigs": [
    {
      "groupId": 0,
      "groupName": "Engagement",
      "groupCategory": "intent",
      "ruleConfigurations": []
    }
  ],
  "maxScore": 100,
  "outputConfiguration": {
    "outputProperty": "hubspot_lead_score",
    "syncEnabled": true
  }
}

A successful response returns 201 with a Location header pointing to the new score resource, with a scoreStatus of "draft".

Publish a draft

To publish a draft, make a POST request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/draft/publish. For new scores, this turns on the score and triggers an evaluation of records. For existing scores, the score is updated and the request triggers a re-evaluation of records based on the updated criteria. A successful response returns the score with a scoreStatus of "published".

Retrieve scores

To retrieve a paginated list of lead scores, make a GET request to /marketing/lead-scoring/2026-09-beta/scores. Include the limit and after query parameters to specify the number of scores returned and to paginate results. The response will look similar to the following, with a results array of score summaries and a paging object for pagination.

{
  "results": [
    {
      "id": "12345",
      "name": "Lead Score",
      "scoreType": "MH",
      "scoredObjectTypeId": "0-2",
      "lastConfigurationChangeTimestamp": "2026-07-20T08:00:00.000Z"
    },
    {
      "id": "56789",
      "name": "Marketing Score",
      "scoreType": "MH",
      "scoredObjectTypeId": "0-1",
      "lastConfigurationChangeTimestamp": "2026-07-25T07:00:00.000Z"
    }
  ],
  "paging": {
    "next": {
      "after": "1011112",
      "link": "https://api.hubapi.com/marketing/lead-scoring/2026-09-beta/scores?limit=2&after=1011112"
    }
  }
}

Retrieve score configurations

To retrieve the published configuration for a score, make a GET request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}.
To retrieve the current draft configuration for a score, make a GET request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/draft.

The response includes all scoring criteria, rules, filters, and timestamps. The scoreStatus field indicates whether the score is published or published_with_draft.

{
  "id": "12345",
  "objectTypeId": "0-1",
  "name": "Lead Score",
  "scoreStatus": "published",
  "scoreType": "MH",
  "groupConfigs": [
    {
      "groupId": 1,
      "groupName": "Engagement Signals",
      "groupCategory": "fit",
      "maxValue": 50.0,
      "ruleConfigurations": [
        {
          "scalingFactor": 1.0,
          "enabled": true,
          "maximumValue": 10.0,
          "configuration": {
            "type": "PROPERTY_RULE",
            "propertyName": "num_unique_forms_submitted",
            "operator": "GT",
            "value": "0"
          }
        }
      ]
    }
  ],
  "outputConfiguration": {
    "outputProperty": "hubspot_lead_score",
    "syncEnabled": true
  },
  "allowedGroupTypes": ["fit", "intent"],
  "maxScore": 100,
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-07-20T08:00:00.000Z",
  "publishedAt": "2026-07-15T16:30:00.000Z"
}

Upsert a draft

To update the active draft for a score, make a PUT request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/draft. This request fully updates the configuration, meaning the entire draft is overwritten with the updated request body. If no draft exists, a new one is created.

{
  "scoreId": 12345,
  "objectTypeId": "0-1",
  "name": "Updated Lead Score",
  "groupConfigs": [
    {
      "groupId": 1,
      "groupName": "Engagement Signals",
      "groupCategory": "intent",
      "maxValue": 60.0,
      "ruleConfigurations": [
        {
          "scalingFactor": 1.0,
          "enabled": true,
          "maximumValue": 15.0,
          "configuration": {
            "type": "PROPERTY_RULE",
            "propertyName": "num_unique_forms_submitted",
            "operator": "GT",
            "value": "0"
          }
        }
      ]
    }
  ],
  "allowedGroupTypes": [
    "fit",
    "intent"
  ],
  "maxScore": 100
}

A successful response returns 200 with the updated draft. Validation failures return a VALIDATION_ERROR response.

Revert a draft to the published configuration

To discard all unpublished changes and revert the draft to the live configuration, make a POST request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/draft/reset. No request body is required. A successful response returns 204 No Content.

Deactivate a score

To turn a score off, while preserving the score configuration, make a POST request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/deactivate. No request body is required. The response returns the score metadata reflecting its new inactive state.

{
  "scoreId": "12345",
  "objectTypeId": "0-1",
  "name": "Lead Score",
  "scoreStatus": "draft",
  "scoreType": "MH",
  "groupConfigs": [],
  "allowedGroupTypes": [],
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-07-28T10:00:00.000Z"
}

The deactivated score returns to a draft which you can update or publish. The score’s groupConfigs are retained.

Clone a score

To duplicate an existing score configuration into a new score, make a POST request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}/clone. In the request body, include the scoreName. This is the name for the new cloned score. If the source score has an active draft, the clone is created from the draft configuration. If no draft exists, the published configuration is cloned.

{
  "scoreName": "Lead Score (Copy)"
}

A successful response returns 201 with the scoreStatus as "draft".

Delete a score

To delete a score, make a DELETE request to /marketing/lead-scoring/2026-09-beta/scores/{scoreId}. No request body is required. A successful response returns 204 No Content.

Read record score values

You can retrieve record score values via the objects API. In your request, retrieve each score’s outputProperty. For example, to retrieve contacts’ value for the New Lead Score, with the output property hubspot_lead_score:

To retrieve an individual contact with their score value, make a GET request to /crm/objects/2026-03/contacts/{recordId}?properties=hubspot_lead_score.
To retrieve all contacts with their score values, make a GET request to /crm/objects/2026-03/contacts?properties=hubspot_lead_score.
To retrieve multiple specific contacts with their score values, make a POST request to /crm/objects/2026-03/contacts/batch/read. In your request body, include the score property in the properties array, and the id values of records to retrieve as inputs. For example:

{
  "properties": ["hubspot_lead_score"],
  "inputs": [
    {
      "id": "1234567"
    },
    {
      "id": "987456"
    }
  ]
}

To search for records with specific score values, use the search API and filter by specific values for the outputProperty. For example, to search for contacts with a New Lead Score (outputProperty:hubspot_lead_score) value over 50, make a POST request to /crm/objects/2026-03/contacts/search and use the following request body:

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hubspot_lead_score",
          "operator": "GT",
          "value": 50
        }
      ]
    }
  ]
}

​Create a lead score

​Publish a draft

​Retrieve scores

​Retrieve score configurations

​Upsert a draft

​Revert a draft to the published configuration

​Deactivate a score

​Clone a score

​Delete a score

​Read record score values