There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Get Lifecycle Stage metrics for Contacts

Last updated May 12, 2023

GET  /contacts/search/v1/external/lifecyclestages

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing & CRM

Required Scope:

crm.objects.contacts.read

Returns the number of contacts that entered the individual lifecycle stages during the provided time period. The time period may be up to a two year window.

Additionally supports aggregating the results by a second property. This property must be an enumerated property (such as a multiple checkbox or dropdown property) with 20 or fewer option. This would support custom enumerated properties.

Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
From Timestamp &fromTimestamp={timestamp}
Query parameter in the URL

A millisecond timestamp representing the start of the time period that you want the stats for.
Note: the time between fromTimestamp and toTimestamp must be 2 years or less.

To Timestamp &toTimestamp={timestamp}
Query parameter in the URL

A millisecond timestamp representing the end of the time period that you want the stats for.
Note: the time between fromTimestamp and toTimestamp must be 2 years or less.


Optional Parameters How to use Description
Aggregation property &aggregationProperty={property name}
Query parameter in the URL
A second optional property to further breakdown the lifecycle stage buckets. This must be an enumerated property with 20 or fewer options.