Skip to content
HubSpot Developer Changelog

Upcoming Validation Change to the Forms API Submission Endpoints

Update: We recently released an amendment to this validation, please see this amendment here: Amendment to Forms API Submission Validation.

From March 21st 2022 we will be rejecting any form submissions that submit fields that aren’t present on the form and submissions that are missing fields that are required on the form


What’s changing? 

Today, HubSpot’s Forms APIs do not require that submission field values are declared ahead of time as fields on the form before submitting data to the API.

From March 21st 2022 we will be rejecting any form submissions that submit fields that aren’t present on the form and submissions that are missing fields that are required on the form. 

Any forms created prior to March 21st 2022 will be unaffected by this validation change for now and continue to work as expected. We will be releasing a migration plan for these existing forms in the coming weeks that we will be sharing with customers and developers, more details to follow on this. However, we still highly recommend that any existing forms are updated to adhere to the validation changes detailed below. 

What this means for developers:

From March 21st 2022, developers who create new form definitions and use any of the following Form API Submission endpoints will need to:

POST https://api.hsforms.com/submissions/v3/integration/submit/:portalId/:formGuid
POST https://forms.hubspot.com/uploads/form/v2/:portal_id/:form_guid
POST https://api.hsforms.com/submissions/v3/integration/secure/submit/:portalId/:formGuid
POST https://api.hsforms.com/submissions/v2/post/upload/secure/:portalId/:formGuid


1. Add missing form fields that are present in submissions to the actual form

Developers will need to stop submitting any fields that are not present on the form itself. This includes form fields that aren’t represented as CRM properties in the associated HubSpot account. Common examples of this are pageUrl and pageTitle. While these are common fields in the submission Context Data optional parameter, these aren’t form field values, and should not be submitted, unless pageurl and pagetitle are CRM properties in the HubSpot account receiving the submission and added as form fields to the form itself. 

2. Make required fields that are missing in submissions non-required on the form


Error message

Developers will see a REQUIRED_FIELD or FIELD_NOT_IN_FORM_DEFINITION error message with a 400 status code in API responses for forms that do not meet the new submission validation.

The Forms API Create and Update endpoints can be used to create new forms with the correct submission fields or update existing forms to obey the new validation rules detailed above.

Create a Form

POST /forms/v2/forms

POST /marketing/v3/forms/


Update an existing Form

PUT /forms/v2/forms/:form_guid

PUT /marketing/v3/forms/{formId}

The CRM Properties API can be used to create CRM properties. 


When is this change happening?


From March 21st 2022 we will be rejecting any form submissions that submit fields that aren’t present on the form and submissions that are missing fields that are required on the form.

Please let us know if you have any feedback or questions by joining the conversation in the community.