Forecasts API (BETA) - HubSpot docs

Supported products

Requires one of the following products or higher.

Sales Hub -Professional

Service Hub -Professional

This functionality is currently in beta. By participating in this beta, you agree to HubSpot’s Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.

The forecast tool in HubSpot allows you track your team’s progress towards customized sales or service targets. You can then use the forecasts API to retrieve data from existing forecasts you’ve created in your HubSpot account.

Please note: this phase of the beta provides read-only endpoints for your forecasts. You cannot currently create, update, or delete forecasts using this API.

Scope requirements

To use the forecast endpoints, you’ll need to authorize the crm.objects.forecasts.read scope for your app.

Retrieve forecast data

To retrieve all forecast submissions in your account, make a GET request to /crm/objects/v3/forecasts and provide any comma-separated properties that you want included in the response using the ?properties query parameter. For example, a GET request to

https://api.hubspot.com/crm/objects/v3/forecasts?properties=hs_created_by_user_id,hs_milestone,hs_team_id,hs_year,hs_included_deal_ids

would result in a response that resembles the following:

{
  "results": [
    {
      "id": "475911884905",
      "properties": {
        "hs_created_by_user_id": "2620022",
        "hs_createdate": "2025-10-10T19:42:51.001Z",
        "hs_lastmodifieddate": "2025-10-14T16:52:43.757Z",
        "hs_milestone": "monthly",
        "hs_object_id": "475911884905",
        "hs_included_deal_ids": "29006642075;29051583857",
        "hs_team_id": "39577840",
        "hs_year": "2025"
      },
      "createdAt": "2025-10-10T19:42:51.001Z",
      "updatedAt": "2025-10-14T16:52:43.757Z",
      "archived": false
    }
  ]
}

You can also retrieve a specific forecast by its ID by making a GET request to crm/objects/v3/forecasts/{id}. The table below provides some common properties you might want to query for when using these APIs.

Property	Type	Description
`hubspot_owner_id`	String	The owner ID for user-level forecasts.
`hs_amount`	Number	The forecasted revenue amount for this submission.
`hs_created_by_user_id`	String	The ID of the HubSpot user who created the forecast. You can use this user provisioning endpoint to get user data from your account.
`hs_deal_pipeline_id`	String	The ID of the specific pipeline set up for the forecast. This field will be `null` if All pipelines was selected when you submitted your forecast.
`hs_fiscal_month`	String	The month number (1-12) for monthly forecasts, if applicable.
`hs_fiscal_quarter`	String	The fiscal quarter (1-4) for quarterly forecasts, if applicable.
`hs_forecast_fiscal_offset`	String	The start month offset to the fiscal year (e.g., `0` = January, `1` = February, etc).
`hs_forecast_start_date`	String	Start date of the forecast, provided as a Unix timestamp (in milliseconds).
`hs_forecast_end_date`	String	End date of the forecast, provided as a Unix timestamp (in milliseconds).
`hs_forecast_type`	String	The ID of the forecast type being used. This value will be set to `0` or `null` for the default forecast type. To retrieve the forecast types available in your account, check out the section below.
`hs_is_all_pipelines`	String	A boolean that indicates whether the forecast applies to all pipelines.
`hs_milestone`	String	An enumeration that denotes the period for which a forecast is submitted. Values include `monthly`, `quarterly`, or `yearly`.
`hs_submission_notes`	String	Optional notes provided by the submitter.
`hs_included_deal_ids`	String	A string that includes a semicolon-delimited list of submitted deals.
`hs_team_id`	String	The ID of the contributing team, if applicable. You can use this user provisioning endpoint to get team data from your account.
`hs_year`	String	The forecast’s year.

Retrieve forecast types

Forecast types define how HubSpot calculates and displays revenue projections in the forecasting tool. Each forecast type requires two properties:

Amount property: the aggregate value used in the forecast (e.g., a deal amount, ARR, or a custom revenue field).
Date property: the time-based field to use for filtering (e.g., a close date or a custom date property).

Every HubSpot account has a default forecast type that uses the standard amount and closedate deal properties. You can create up to four additional custom forecast types to forecast on different revenue metrics, such as forecasting on a Services Amount property for one-time or ongoing professional services revenue.

When you create a custom forecast type, HubSpot automatically generates the supporting calculated properties to provide multi-currency support and probability-weighted projections.
If your account has deal splits enabled, a matching set of properties will also be created on the deal split object.

To retrieve the forecast types that you’ve configured in your account, make a GET request to /forecasting-settings/v3/forecast-types. For example, to get all available forecast types, you’d make a GET request to https://api.hubspot.com/forecasting-settings/v3/forecast-types. A successful response will resemble the following:

{
  "results": [
    {
      "forecastName": "joe forecast",
      "objectTypeId": "0-3",
      "amountProperty": "amount",
      "dateProperty": "closedate",
      "amountInHomeCurrencyProperty": "amount_in_home_currency",
      "weightedAmountInHomeCurrencyProperty": "hs_projected_amount_in_home_currency",
      "weightedAmountProperty": "hs_projected_amount",
      "dealSplitProperties": null,
      "updatedTimestamp": 1760124698903,
      "createdAtTimestamp": 1760124698903,
      "forecastTypeId": 16142707,
      "updatedBy": 2620022,
      "createdBy": 2620022,
      "amountOrDatePropertyRestrictedForUser": false,
      "id": "16142707",
      "updatedAt": "2025-10-10T19:31:38.903Z",
      "createdAt": "2025-10-10T19:31:38.903Z",
      "defaultType": false
    }
  ]
}

You can also retrieve a specific forecast type by its ID by making a GET request to /forecasting-settings/v3/forecast-types/{id}. The table below provides the properties available for each forecast type:

Property	Type	Description
`objectTypeId`	String	The CRM object type this forecast applies to. Currently only deals (`0-3`) are supported.
`amountInHomeCurrencyProperty`	String	The property containing the amount converted to the account’s home currency. For multi-currency accounts, this enables consistent aggregation across deals in different currencies.
`updatedAt`	String	The date when the forecast type was last updated (as an ISO 8601 date).
`updatedBy`	Number	The ID of the HubSpot user who last updated the type.
`weightedAmountProperty`	String	The property containing the amount multiplied by the deal’s win probability. Used to calculate probability-weighted pipeline projections.
`updatedTimestamp`	Number	The date when the forecast type was last updated (as a Unix timestamp in milliseconds).
`defaultType`	Boolean	Whether this is the account’s default forecast type. The default type uses the standard `amount` and `closedate` properties and cannot be deleted.
`createdAt`	String	The date when the forecast type was last created (as an ISO 8601 date).
`dealSplitProperties`	Object	When deal splits are enabled, contains the corresponding deal split object properties for amount, date, and currency calculations. `null` if deal splits are not configured.
`createdAtTimestamp`	Number	The date when the forecast type was created (as a Unix timestamp in milliseconds).
`amountProperty`	String	The deal property used as the revenue value for forecasting (e.g., `amount`, `arr`, or a custom currency property). This is the primary value that gets rolled up in forecast views.
`createdBy`	Number	The ID of the HubSpot user who created the type.
`forecastTypeId`	Number	The ID of the forecast type (represented as a number).
`dateProperty`	String	The deal property used to determine which time period a deal falls into (e.g., `closedate` or a custom date property). Deals are included in a forecast period based on this date.
`id`	String	The ID of the forecast type.
`amountOrDatePropertyRestrictedForUser`	Boolean	A boolean that indicates whether any of the properties in forecast type is restricted for users who aren’t super admins. If `true`, these users won’t be able to access this forecast type.
`forecastName`	String	The name of the forecast type.
`weightedAmountInHomeCurrencyProperty`	String	The name of the property used to calculate the weighted amount in the account’s home currency.

Deal split properties

When deal splits are enabled for an account, the returned forecast type includes a populated dealSplitProperties object. Deal splits allow a single deal’s revenue to be divided among multiple owners based on percentages. Because deal splits are stored as a separate CRM object type, forecasts require additional properties to aggregate split amounts correctly. The dealSplitProperties property in the response maps the forecast type’s amount and date properties to their corresponding deal split equivalents. Based on whether the forecast type is aggregated from the deal object or the deal split object, the following properties are provided within dealSplitProperties: Deal related properties The following properties are used when aggregating from the deal object:

Property	Type	Description
`dealCustomAmountProperty`	String	The calculated property on the deal object that stores the custom amount value. Used as the source for deal split calculations.
`dealCustomDateProperty`	String	The date property on the deal object used for time-based filtering. Typically matches the forecast type’s `dateProperty`.
`dealCustomAmountPropertyInHomeCurrency`	String	The calculated property on the deal object containing the custom amount converted to home currency.

Deal split related properties The following properties are used when aggregating from the deal split object:

Property	Type	Description
`dealSplitCustomAmountProperty`	String	The property on the deal split object containing each owner’s portion of the custom amount (amount * split percentage).
`dealSplitCustomAmountPropertyInHomeCurrency`	String	The property on the deal split object containing each owner’s portion converted to home currency.
`dealSplitWeightedCustomAmountProperty`	String	The property on the deal split object containing each owner’s portion multiplied by win probability.
`dealSplitWeightedCustomAmountPropertyInHomeCurrency`	String	The property on the deal split object containing each owner’s weighted portion in home currency.

If a HubSpot user views their individual forecast with deal splits enabled:

HubSpot will query the corresponding deal_split object instead of the deal object.
HubSpot will use the dealSplitCustomAmountProperty field to get each sales rep’s portion of the revenue.
Currency conversion will use the value defined in the dealSplitCustomAmountPropertyInHomeCurrency field.
Weighted projections will use the value defined in either the dealSplitWeightedCustomAmountProperty or dealSplitWeightedCustomAmountPropertyInHomeCurrency fields.

This behavior ensures that when a $100,000 deal is split 60/40, one sales rep will see $60,000 in their forecast, while the other rep will see $40,000, rather than both seeing the full $100,000. The code block below provides an example response from making a GET request to /forecasting-settings/v3/forecast-types with the dealSplitProperties property populated:

{
  "results": [
    {
      "forecastName": "Net New ARR Forecast",
      "objectTypeId": "0-3",
      "amountProperty": "net_new_arr",
      "dateProperty": "closedate",
      "amountInHomeCurrencyProperty": "hs_net_new_arr_in_home_currency",
      "weightedAmountInHomeCurrencyProperty": "hs_weighted_net_new_arr_in_home_currency",
      "weightedAmountProperty": "hs_weighted_net_new_arr",
      "dealSplitProperties": {
        "dealCustomAmountProperty": "hs_net_new_arr",
        "dealCustomDateProperty": "closedate",
        "dealCustomAmountPropertyInHomeCurrency": "hs_net_new_arr_in_home_currency",
        "dealSplitCustomAmountProperty": "hs_deal_split_net_new_arr",
        "dealSplitCustomAmountPropertyInHomeCurrency": "hs_deal_split_net_new_arr_in_home_currency",
        "dealSplitWeightedCustomAmountProperty": "hs_deal_split_weighted_net_new_arr",
        "dealSplitWeightedCustomAmountPropertyInHomeCurrency": "hs_deal_split_weighted_net_new_arr_in_home_currency"
      },
      "forecastTypeId": 16272973,
      "id": "16272973",
      "defaultType": false,
      "amountOrDatePropertyRestrictedForUser": false,
      "createdBy": 2620022,
      "updatedBy": 2620022,
      "createdAt": "2025-09-15T14:22:10.000Z",
      "updatedAt": "2025-09-15T14:22:10.000Z",
      "createdAtTimestamp": 1726409930000,
      "updatedTimestamp": 1726409930000
    }
  ]
}

​Scope requirements

​Retrieve forecast data

​Retrieve forecast types

​Deal split properties

Scope requirements

Retrieve forecast data

Retrieve forecast types

Deal split properties