Breaking Change: CRM API Write Validation Enforcement Starting with the 2026-09 API Version

Starting with the /2026-09/ API version shipping on September 8, 2026, HubSpot will enforce admin-configured validation rules on all CRM API write paths. If your integration creates or updates CRM records, please make sure that it conforms to the below changes before updating your version of the API.

What's Changing

When a HubSpot admin configures rules governing how records are created or modified (conditional required properties, required fields on the Create Record form, or user-level association permissions), those rules will now apply to API writes, not just actions taken in the HubSpot UI. While this is a breaking change in that you will get error messages, these changes exist to help your app avoid making changes that violate HubSpot user's expectations which could put their data into strange states that run contrary to their rules.

Three behaviors are being enforced:

Conditional required properties. If an admin has configured a rule that makes a property required when another property has a specific value (for example, close_date becomes required when dealstage is set to closedwon), the API will return a 400 validation error if that property is missing on write. Previously, these rules were UI-only and the API ignored them.

//Example of an error { "category": "VALIDATION_ERROR", "message": "...", "errors": [ { "code": "MISSING_CONDITIONAL_REQUIRED_PROPERTY", "message": "my_property is required because of a conditional property rule based on [country]", "context": { "propertyName": [ "my_property" ] } } ] }

Record creator settings. If an admin has marked specific properties or associations as required at record creation time in Settings → Objects → [Object Type] → Create Record, the API will enforce those requirements on POST calls.

//Example of an error { "status": "error", "category": "VALIDATION_ERROR", "message": "The property values provided are invalid", "errors": [ { "code": "MISSING_REQUIRED_PROPERTY", "message": "A value for firstname must be provided", "context": { "propertyName": [ "firstname" ] } } ] }

Edit Associations permission. If your app uses user-level OAuth and the installing user does not have the "Edit Associations" permission (CRM_ASSOCIATIONS_WRITE_ACCESS scope), API calls that create, update, or delete associations will return an error. This does not affect portal-level app tokens.

//Example of an error { "status": "error", "message": "Missing 'Edit Associations' permission.", "category": "VALIDATION_ERROR" }

These behaviors only apply when an admin has actively configured these rules on a portal. If no conditional required property rules, record creator requirements, or association permission restrictions exist on a portal, there is no behavior change.

How to prepare

Suggest users of your integration to review the account your app writes to. Check Settings → Properties for conditional required rules, Settings → Objects → [Object] → Create Record for required field settings, and Settings → Users & Teams to confirm your app's installing user has the appropriate permissions.
Fetch current property definitions via GET /crm/{version}/properties/{objectType} to identify required fields before your write calls.
Ensure your write calls include all conditionally required properties when the controlling property value is set.
Ensure POST calls to create records include all properties and associations marked as required in Create Record settings.
If your app uses user-level OAuth, confirm the installing user has "Edit Associations" enabled, or remove association writes from your app's scope if not needed.

Handling validation errors

When enforcement is active, API write calls may return 400 Bad Request if the request violates an admin-configured rule. These errors indicate that the portal's configuration requires something your request didn't include, not necessarily a problem with your integration's logic.

Parse the error message. Each violation returns a specific message identifying the rule that was violated (e.g., "Property 'close_date' is required when 'dealstage' is set to 'closedwon'." or "Missing 'Edit Associations' permission.").
Re-check portal configuration. The rule may have been added or changed by an admin after your integration was last configured. Poll GET /crm/v3/properties/{objectType} to detect changes to required fields.
Retry with corrected input. Adjust your request to satisfy the rule and retry. Do not retry the same request unchanged.
Surface actionable errors to your users. Translate the validation message into guidance they can act on (e.g., "This portal requires a Close Date when Deal Stage is Closed Won").

Datetime validation improvements

The CRM API now handles datetime property inputs more permissively. Previously, valid inputs like off-midnight date values, ISO-8601 strings, or epoch-second timestamps could be rejected with errors like INVALID_DATE or cryptic range messages. The API now normalizes these inputs and returns a successful response with a new warnings array on the response object that describes any normalization that occurred. Error messages for genuine failures have also been improved to include the raw input, the parsed interpretation, and which constraint was violated.

If you want to surface normalization notices to users, read the warnings field from write responses. If your integration is expecting a certain shape to the error message, confirm that it is updated to this new shape.

{ "category": "PROPERTY_VALUE_NORMALIZED", "context": { "normalizedValue": "631152000000", "propertyName": "date_of_birth", "rawValue": "1990-01-01T00:00:00Z" }, "message": "date_of_birth was normalized" }

When is it happening?

Enforcement goes into effect on September 8, 2026, with the release of the /2026-09/ API version. To learn more about HubSpot's date-based API versioning and how to migrate, see the Date-Based Versioning guide.

Questions or comments? Join us in the developer forums.

HubSpot Developer Changelog