Update Lifecycle Stage Using API



I’m attempting to update the Lifecycle Stage from “Opportunity” back to “Lead” using a POST API call to Hubspot. I seem to get a successful 204 Response from the request, but the change was not made. Here’s the code I’m using (python):

api_key = '?hapikey=' + api_key_value
header = {'Content-Type': 'application/json'}
hs_api_url = 'http://api.hubapi.com/contacts/v1/contact/email/' + email_address + '/profile'
properties = {'properties': [{'property': 'lifecyclestage', 'value': 'lead'}]}
hubspot_response = requests.post(hs_api_url + api_key, headers=header, data=json.dumps(properties))

Am I doing something wrong in the call, or is there a limitation in Hubspot that doesn’t allow a Contact to move “back” to a Lead?

Please assist. Thank you!


Hi @cschouten

Normally the lifecycle stage cannot move backwards, so if a record is an opportunity, it can’t go straight to lead. You’d need to first set the value to "" (empty string), then (in a separate request) set the earlier lifecycle stage value.


How to set the lifecycle stage = “” This should be done somewhere in the settings / preferences?


@dadams, Thanks so much for this insight. It worked just as you described, but unfortunately now we’re running into Hubspot’s API rate limits.As a result we’re working to migrate these requests to the Hubspot batch create/update API endpoint (http://developers.hubspot.com/docs/methods/contacts/batch_create_or_update).

Do you know if the records passed into this batch API endpoint are processed synchronously and in the order provided? I’m wondering if in the cases where I would have cleared the contact’s lifecycle stage, I can just insert an additional record into this batch to perform this “clearing” action before applying the lifecycle stage I actually want the contact to end up in.


Just to close the loop, based on my testing the batch API does not guarantee synchronous, in order processing, so based on this the reset operation (i.e. setting the lifecycle stage to '') needs to be done using a one-off update request.


@hstrowd if there are multiple updates to a contact record in a single batch update, those updates get merged, so it won’t be possible to include the reset and the update in the same batch. It would be possible to use the batch API to do the reset, and then set the lifecycle in a second batch, but you would need to verify that the reset had been processed before setting the new lifecycle.

Is is this something that you anticipate needing to do with a large number of contacts on a regular basis? If this is something that you need to do once, it is possible to use a workflow to do this:


@dadams I appreciate the follow up. Merging all updates to a contact record in a single batch makes sense and explains the behavior I was seeing.

Our current workflow is to set the lifecycle stage for customers that cancel their membership or “churn” to the other stage. This means that if/when these customers reactivate their membership, which happens from time to time, we want to reset the lifecycle stage for their Hubspot contact back to customer. This is the only time we move contacts backwards in the lifecycle but it does happen to a non-trivial number of customers in our system and is something we’d like to be able to handle programmatically.

For the time being, I’m just handling the lifecycle reset change using the one-off synchronous API endpoint and allowing all other changes to be batched up and processed in bulk. This will hopefully get us under the Hubspot rate limit thresholds. I’ll let you know if I find out otherwise, in which case I might pick your brain further about alternative solutions. Thanks so much for your help.