Get Lifecycle Stage metrics for Contacts

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Headers

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.

JSON

Example GET URL (without additional aggregation): https://api.hubapi.com/contacts/search/v1/external/lifecyclestages?fromTimestamp=1514764800000&toTimestamp=1519862400000 Example response: [ { "lifecycleStage": "hs_lifecyclestage_lead_date", "count": 34657 }, { "lifecycleStage": "hs_lifecyclestage_opportunity_date", "count": 1 }, { "lifecycleStage": "hs_lifecyclestage_marketingqualifiedlead_date", "count": 3 }, { "lifecycleStage": "hs_lifecyclestage_salesqualifiedlead_date", "count": 0 }, { "lifecycleStage": "hs_lifecyclestage_evangelist_date", "count": 0 }, { "lifecycleStage": "hs_lifecyclestage_customer_date", "count": 242 }, { "lifecycleStage": "hs_lifecyclestage_subscriber_date", "count": 39 }, { "lifecycleStage": "hs_lifecyclestage_other_date", "count": 0 } ] Example with aggregation using hs_analytics_source: https://api.hubapi.com/contacts/search/v1/external/lifecyclestages?fromTimestamp=1514764800000&toTimestamp=1519862400000&aggregationProperty=hs_analytics_source Example response: [ { "lifecycleStage": "hs_lifecyclestage_lead_date", "count": 34657, "aggregation": { "count": 34657, "aggregations": { "hs_analytics_source": [ { "key": "DIRECT_TRAFFIC", "count": 30794 }, { "key": "OFFLINE", "count": 3822 }, { "key": "PAID_SOCIAL", "count": 18 } ] } } }, { "lifecycleStage": "hs_lifecyclestage_opportunity_date", "count": 1, "aggregation": { "count": 1, "aggregations": { "hs_analytics_source": [ { "key": "OFFLINE", "count": 1 } ] } } }, { "lifecycleStage": "hs_lifecyclestage_marketingqualifiedlead_date", "count": 3, "aggregation": { "count": 3, "aggregations": { "hs_analytics_source": [ { "key": "DIRECT_TRAFFIC", "count": 2 }, { "key": "OFFLINE", "count": 1 } ] } } }, { "lifecycleStage": "hs_lifecyclestage_salesqualifiedlead_date", "count": 0, "aggregation": { "count": 0, "aggregations": { "hs_analytics_source": [] } } }, { "lifecycleStage": "hs_lifecyclestage_evangelist_date", "count": 0, "aggregation": { "count": 0, "aggregations": { "hs_analytics_source": [] } } }, { "lifecycleStage": "hs_lifecyclestage_customer_date", "count": 242, "aggregation": { "count": 242, "aggregations": { "hs_analytics_source": [ { "key": "OFFLINE", "count": 169 }, { "key": "DIRECT_TRAFFIC", "count": 73 } ] } } }, { "lifecycleStage": "hs_lifecyclestage_subscriber_date", "count": 39, "aggregation": { "count": 39, "aggregations": { "hs_analytics_source": [ { "key": "DIRECT_TRAFFIC", "count": 26 }, { "key": "OFFLINE", "count": 13 } ] } } }, { "lifecycleStage": "hs_lifecyclestage_other_date", "count": 0, "aggregation": { "count": 0, "aggregations": { "hs_analytics_source": [] } } } ]