topic Re: Please ensure deal stage history is available via the API in APIs & Integrations

Please ensure deal stage history is available via the API

nateangell — Thu, 25 Jun 2020 02:32:40 GMT

Because HubSpot does not provide a good way to see full deal history through stages, we had been using an API call like https://api.hubapi.com/deals/v1/deal{dealId}?hapikey={hapikey} to return properties on deals, and we were especially focused on getting properties like hs_date_entered_{stageId} and hs_date_exited(stageId} so we could visualize/analyze historical deal stage movement, but those properties disappeared from the results during May–June 2020.

We did have some luck geting this info with the new API, with calls like: https://api.hubapi.com/crm/v3/objects/deals/979797171?archived=false&properties=hs_date_entered_*&hapikey=[key]

But we have heard from HubSpot support (Ticket number: #3481971) that this information may not be consistently available via any API call in the future. Please don't make it unavailable! This is the only workaround to address a serious deficiency in HubSpot's native reporting capabilities! See the community forums for consistent outcry for this missing feature: https://community.hubspot.com/t5/CRM/How-to-view-historical-deal-stages/m-p/338251#M119526

Re: Please ensure deal stage history is available via the API

Derek_Gervais — Thu, 25 Jun 2020 19:29:29 GMT

Hey @nateangell ,

Just to clarify: Are you looking to see all deal stages a particular deal has been in? You should be able to see this by looking at the property history for `dealstage` for a given deal. The properties you're referring to are pseudo-properties that are only used for some internal functions, and won't be available long term. However, a call like this:

https://api.hubapi.com/deals/v1/deal/12345?hapikey=xxxx&includePropertyVersions=true

Will return a given deal record with a full property history. Using this, you can identify every deal stage that a particular deal was in and when.

Re: Please ensure deal stage history is available via the API

nateangell — Thu, 25 Jun 2020 20:51:49 GMT

Thanks. The HS team has pointed this out several times. And sure, one can see the history for a specific deal if one looks at this history. The need tho is to understand historical deal flow across hundreds of deals across all time. This UX view doesn't really help with that need.

Most organizations like to be able to look at a snapshot of deals at particular times: how many deals were in each stage on 1 Mar 2020? On 1 Jan? A year before that, etc. Near as I can tell, the funnel views in HS only do reporting on deals that go through EVERY funnel stage (eg, never jump a stage, which is NEVER true for us) or the overall current state of the funnel. We want to know for each month: how many deals came into each stage, how many left, and how many remained. We use the API to get this data and reconstruct the funnel outside HS. It's a huge pain, but it seems like the only way to do it now, so we'd appreciate at least not losing API access to this key info.

Re: Please ensure deal stage history is available via the API

nateangell — Thu, 25 Jun 2020 22:45:25 GMT

ARGH! I just learned that one can export entire deal stage histories from the property itself in settings. The part I missed was that you can export all the histories for all the deals from the property in addition to seeing the history for just one deal. This is the incredibly simple solution for this need that I didn't see clearly suggested till now, hence our needless trip to the API and redesign once the APIs changed.

Yes it would be nice if there were a report one could build in the UX for this, but at least the data is easily available without using the API. SIGH...

Re: Please ensure deal stage history is available via the API

davidrevis — Fri, 14 May 2021 12:34:00 GMT

Thank you! @nateangell This was exactly what I was after and was trying complicated API exports and yes it was there all the time!

Re: Please ensure deal stage history is available via the API

Augustus — Mon, 19 Jul 2021 19:57:48 GMT

@Derek_Gervais thanks for the link to deals API to reference "includePropertyVersions=true" to pull the historical statuses of each deal property

https://api.hubapi.com/deals/v1/deal/12345?hapikey=xxxx&includePropertyVersions=true

This looks like this is from the v1 API - is there an v3 API version of this link because I don't see "includePropertyVersions" in the list of params on the Deals API?

The primary goal I'm trying to achieve is to know when each deal entered and changed its deal pipeline/stage for reporting purposes.

Re: Please ensure deal stage history is available via the API

MPatel — Thu, 09 May 2024 16:42:36 GMT

https://api.hubapi.com/crm/v3/objects/deals?propertiesWithHistory=dealstage

Does the trick

Re: Please ensure deal stage history is available via the API

bromanguarantor — Mon, 21 Apr 2025 18:00:39 GMT

I'm having a similar issue when trying to call the dealStage history via a custom coded action. I found that HubSpot custom coded actions do not return full property history, even when using propertiesWithHistory=dealstage. The history is visible in UI/exportable, but not exposed in workflow-bound custom code. It did work when using:

Postman
Private apps
External servers calling the API

But not within HubSpot's workflows themselves. I repeatedly get the error "Not enough stage history available." even on deals that have been in our database for months, and have had many changes.