Breaking Change: Enhanced Validations for Non-String Properties in HubSpot's CRMObject APIs
Starting April 7th, 2025, HubSpot will implement enhanced validations for non-string property values, including enumeration and multi-value enumeration property values submitted via the CRMObject APIs. This change aims to improve data integrity and user experience by prohibiting leading or trailing whitespace characters, including invisible unicode characters, from these property values. Additionally, existing non-string property values and enumeration options will be backfilled to remove any whitespace or invisible characters from the beginning or end of all property values.
What's changing?
Stricter Validation for Non-String Properties
Current Behavior: Enumeration values and other non-string properties that include leading or trailing whitespace characters, including invisible unicode characters (e.g., no-break spaces), are accepted and may lead to data inconsistencies or reporting issues.
New Behavior: Non-string property values, including enumeration options and multi-value enumeration properties, must not contain leading or trailing whitespace or invisible unicode characters. Values with these characters will result in a 400 Bad Request error with a VALIDATION_ERROR category, providing details on the validation issues encountered.
Error Message Example:
{
"status": "error",
"message": "Property values were not valid: [{\"isValid\":false,\"message\":\"\"{{input_value}}\" includes leading or trailing whitespace.\",\"error\":\"LEADING_TRAILING_WHITESPACE\",\"name\":\"property_name\"}]",
"correlationId": "{{sample_correlation_id}}",
"category": "VALIDATION_ERROR"
}
Backfilling of Existing Non-String Properties
All existing non-string property values and enumeration options will be backfilled to remove any whitespace or invisible characters from the beginning or end of all property values.
What does this mean for developers?
Ensure all data submissions via the CRMObject APIs for non-string properties, including enumeration options and multi-value enumeration properties, strictly adhere to the new validation rule. Developers should review and update any integrations, scripts, or automated processes that submit non-string property values to HubSpot to ensure compliance with the new validation rules.
Lastly, error-handling routines should be implemented or updated to manage responses from the CRMObject APIs that indicate invalid non-string property values due to the enhanced validations.
For example:
Before the Change for Enumeration Options: If the valid enumeration options are ["one", "two", "three"], submitting a value like " two" (with leading space) or "two " (with trailing space) would be accepted.
After the Change for Enumeration Options: Submitting " two" or "two " as an enumeration value will result in a 400 Bad Request error with a VALIDATION_ERROR response because it contains leading or trailing whitespace or invisible characters.
Before the Change for Non-String Property Values: Submitting a property value like ‘“ 7”’ (a string with a leading space before the digit) would have been accepted.
After the Change for Non-String Property Values: Submitting a value like ‘“ 7”’ or ‘“7 “‘ for a number property will now trigger a 400 Bad Request error, with the response indicating a VALIDATION_ERROR.
Important Note: the original release date for this change was initially scheduled for January 6th, 2025, but to better accommodate our customers, we are extending the release date to April 7th, 2025.
If you have questions or comments, join us in the peer-to-peer developer forums below.
"All existing non-string property values and enumeration options will be backfilled to remove any whitespace or invisible characters from the beginning or end of all property values."
This certainly indicates that somebody has some way to find all these occurrences. Can we get those results for our existing environments? If we have no occurrences of this, it would be an easy way to avoid digging thru code and running tests to determine "if" we have the problem.
Thank you for bringing up these concerns. We understand the importance of being able to test these changes in non-production environments, and we’re actively working on a solution that will allow for that. Our team is currently exploring options for making these validations available in a controlled manner, and we'll have more information soon.
We appreciate the suggestion regarding the backfilled values. We’re investigating the feasibility of providing more insights on this front, though there are a few technical and logistical considerations we need to work through. We’ll keep you updated as we make progress!
Breaking Change: Enhanced Validations for Non-String Properties in HubSpot's CRMObject APIs
Hi @04838 - Thank you for reaching out! Apologies for the delay.
Regarding the ability to test backfill changes in non-production environments, I want to clarify that currently, users are unable to test these specific backfill changes in non-production environments. This limitation is due to how these changes are rolled out and managed across our systems.
As for the request for reports or visibility into occurrences of these issues, unfortunately, the team won't be able to provide this level of granular detail for every breaking change. The tooling and processes required for such detailed analysis across multiple environments are not in place, especially given the volume of ongoing breaking changes we are currently handling.
I understand this may be frustrating, but rest assured that we are executing all necessary backfill processes to ensure a smooth transition.
Should anything change I will make sure to update everyone here with that information as soon as I'm aware.
Breaking Change: Enhanced Validations for Non-String Properties in HubSpot's CRMObject APIs
How can we test this before it goes live. Will it be switched on on sandboxes or other non-production portals before the change is deployed to all portals?
Breaking Change: Enhanced Validations for Non-String Properties in HubSpot's CRMObject APIs
Hi @AndrewGallacher - Thank you for bringing up these concerns! As I commented above, we recognize the importance of being able to test these changes in a non-production environment, and we’re trying to work on a solution that will allow for that. Our team is currently exploring options for making these validations available in a controlled manner, and we'll have more information soon.
Breaking Change: Enhanced Validations for Non-String Properties in HubSpot's CRMObject APIs
Hi @hseligson , Are you able to give me any update on how I will be able to test that our integration code complies with these new validation rules or if our data setup will be affected by the data cleanup mentioned. It is now just about a month until this goes live and that month includes a significant holiday period for most us.
Breaking Change: Enhanced Validations for Non-String Properties in HubSpot's CRMObject APIs
Hi @AndrewGallacher, Thank you for your follow-up! We have extended the live date for this change to April 7, 2025. We will also introduce a public beta for this change in mid-January. I will make a note to follow up with you during that time to share more details about how to enroll in this beta and test it.