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.

For the changes to the beta v3 Forms API, please see this separate post.

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 selectedExternalOptions field.

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.

If the 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 FIELD_HAS_EXTERNAL_OPTIONS error.

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 "marketingqualifiedlead":

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.