Changes to the lifecycle stage in forms
Note: This post has been updated to reflect the new date that the changes will go live. The changes to the legacy v2 Forms API will now go into effect on March 19, 2024.
We're changing how the lifecycle stage for CRM records is handled in forms. Instead of being a form field, the lifecycle stage will be included in the form settings in a new
What's changing for form submissions?
The current method of including the lifecycle stage in the
lifecyclestage form field will continue to work after this change. If a valid lifecycle stage is included in this field, it will be used for the resulting CRM record as it will override any lifecycle settings for the form. The `lifecyclestage` field will be accepted in the submission even if the field is not in the form definition.
lifecyclestage field is not included in the submission, then it will use the lifecycle stage set in the form definition. If no lifecycle stage is set up in the form definition, then it will fall back to the default lifecycle stage for the HubSpot account.
What's changing for form definitions?
Forms will no longer have a
lifecyclestage field, and will instead have the lifecycle included in a new
selectedExternalOptions field in the form definition. Trying to create or update a form definition that includes the
lifecyclestage field will result in a
formFieldValidationErrors error, with the specific details including a
In order for the form to set the lifecycle stage of any objects, the
selectedExternalOptions must include entries for both contacts and companies, even if the form only includes fields for contacts or only for companies, or you will get an
INVALID_LIFECYCLE_STAGE error. The example below sets the lifecycle for both the contact (
"objectTypeId": "0-1") and company (
"objectTypeId": "0-2") to
Existing forms that currently have the
lifecyclestage field will not be modified, but the form cannot be updated without removing the
lifecyclestage field from the form. Any attempts to update the definition for a form that still include the
lifecyclestage field will return an error.
When is this happening?
The change to form submissions without the lifecycle stage is going into effect immediately. Existing form submissions that include the
lifecyclestage field will not be affected as the included field will continue to override the form settings.
The change to how form definitions are handled in the beta Forms v3 API is also going into effect immediately.
The legacy v2 Forms API will start showing the
selectedExternalOptions property and returning an error when the
lifecyclestage field is included on any form definitions beginning on March 19, 2024.
Please let us know if you have any questions by joining the conversation in our community.