Forecasts API (BETA) - HubSpot docs

Supported products

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/2026-09-beta/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/2026-09-beta/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/2026-09-beta/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_forecast_month`	String	The month number (1-12) for monthly forecasts, if applicable.
`hs_forecast_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 submission history

To retrieve the history of forecast submissions as events, make a GET request to /forecast-submissions/2026-09-beta/events, and include any of the query parameters detailed in the table below. Results are returned in descending chronological order (most recent first) and are paginated using a cursor.

Query parameters

Parameter	Type	Description
`occurredAfter`	Number	Return only events that occurred after this time, provided as a Unix timestamp in milliseconds. If omitted, all history is returned.
`occurredBefore`	Number	Return only events that occurred before this time, provided as a Unix timestamp in milliseconds. Defaults to the current time.
`limit`	Number	Maximum number of events to return per page. Defaults to `100` (the maximum allowed).
`after`	String	Cursor token from a previous response’s `paging.next.after` field. Use this to retrieve the next page of results.

A successful response will resemble the following:

{
  "results": [
    {
      "objectType": "FORECAST",
      "objectId": "475911884905",
      "occurredAt": "2025-10-14T16:52:43.757Z",
      "archived": false,
      "properties": {
        "hs_amount": "75000.00",
        "hs_created_by_user_id": "2620022",
        "hs_change_in_amount": "5000.00",
        "hs_submission_notes": "Pulled in two deals from Q4",
        "hubspot_owner_id": "391782",
        "hs_deal_pipeline_id": "default",
        "hs_milestone": "monthly",
        "hs_forecast_month": "10",
        "hs_year": "2025",
        "hs_forecast_start_date": "2025-10-01T00:00:00Z",
        "hs_forecast_end_date": "2025-10-31T00:00:00Z",
        "hs_is_all_pipelines": "false",
        "hs_included_deal_ids": "29006642075;29051583857",
        "hs_team_id": "39577840",
        "hs_forecast_type": "0"
      }
    },
    {
      "objectType": "FORECAST",
      "objectId": "475911884905",
      "occurredAt": "2025-10-10T19:42:51.001Z",
      "archived": false,
      "properties": {
        "hs_amount": "70000.00",
        "hs_created_by_user_id": "2620022",
        "hs_change_in_amount": "0.00",
        "hs_submission_notes": "",
        "hubspot_owner_id": "391782",
        "hs_deal_pipeline_id": "default",
        "hs_milestone": "monthly",
        "hs_forecast_month": "10",
        "hs_year": "2025",
        "hs_forecast_start_date": "2025-10-01T00:00:00Z",
        "hs_forecast_end_date": "2025-10-31T00:00:00Z",
        "hs_is_all_pipelines": "false",
        "hs_included_deal_ids": "29006642075",
        "hs_team_id": "39577840",
        "hs_forecast_type": "0"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "eyJhZnRlciI6Ijk..."
    }
  }
}

Each event represents a single forecast submission action, which can either be the initial submission or a subsequent update. A single forecast object may have multiple events if its amount was updated over time.

Event properties

Each event in the response includes the following top-level fields:

Field	Type	Description
`objectType`	String	The CRM object type. Always `"FORECAST"` for this endpoint.
`objectId`	String	The ID of the `FORECAST` CRM object this submission belongs to.
`occurredAt`	String	The date and time the submission occurred, as an ISO 8601 timestamp.
`archived`	Boolean	Whether the associated `FORECAST` object has been deleted. When `true`, forecast context properties will be absent from the `properties` map.
`properties`	Object	A map of submission and forecast context fields. See below for details.

The properties map contains two kinds of fields: point-in-time submission values captured when the event occurred, and context fields hydrated from the associated forecast object. The following submission properties are captured at the moment of submission:

Property	Type	Description
`hs_amount`	String	The forecasted revenue amount submitted by the sales rep.
`hs_created_by_user_id`	String	The ID of the HubSpot user who submitted the forecast.
`hs_change_in_amount`	String	The change in amount relative to the previous submission. Positive values indicate an increase; negative values indicate a decrease.
`hs_submission_notes`	String	Optional free-text notes provided at the time of submission.

The following context properties are hydrated from the associated forecast object:

Property	Type	Description
`hubspot_owner_id`	String	The owner ID of the sales rep this forecast belongs to.
`hs_deal_pipeline_id`	String	The ID of the pipeline associated with this forecast. `null` if All pipelines was selected.
`hs_forecast_start_date`	String	Start date of the forecast period, provided as an ISO 8601 timestamp.
`hs_forecast_end_date`	String	End date of the forecast period, provided as an ISO 8601 timestamp.
`hs_milestone`	String	The period type for the forecast. Values include `monthly`, `quarterly`, or `yearly`.
`hs_forecast_month`	String	The month number (1–12) for monthly forecasts.
`hs_forecast_quarter`	String	The fiscal quarter (1–4) for quarterly forecasts.
`hs_year`	String	The year the forecast covers.
`hs_forecast_fiscal_offset`	String	The start month offset of the fiscal year (e.g., `0` for January, `1` for February, etc).
`hs_forecast_type`	String	The ID of the forecast type used. `0` or `null` for the default type.
`hs_is_all_pipelines`	String	Whether the forecast applies to all pipelines.
`hs_team_id`	String	The ID of the contributing team, if applicable.
`hs_included_deal_ids`	String	Semicolon-delimited list of deal IDs explicitly included in this submission.

If the forecast object associated with an event has been deleted, the event will still be returned but archived will be set to true and the forecast context properties will be absent.

Pagination

Results are paginated using a cursor. To retrieve the next page, pass the after value from paging.next.after in the previous response as the after query parameter. When paging is absent from the response, you have reached the last page.

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/2026-09-beta/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/2026-09-beta/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/2026-09-beta/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 submission history

​Query parameters

​Event properties

​Pagination

​Retrieve forecast types

​Deal split properties

Scope requirements

Retrieve forecast data

Retrieve forecast submission history

Query parameters

Event properties

Pagination

Retrieve forecast types

Deal split properties