Developer Announcements

rhenry
HubSpot Employee
HubSpot Employee

Upcoming Validation Change to the Forms API Submission Endpoints

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 questions by replying below.

Rahmona Henry
1 Reply 1
mciprian
Member

Upcoming Validation Change to the Forms API Submission Endpoints

Has this change already come into effect? We are already seeing this error while submitting forms on non HubSpot pages. The forms on HubSpot pages do work, but not the external ones. No changes were made in both json and the hubspot forms. Since March 11th, we are receiving an "UNKNOWN_VALIDATION_ERROR" , with the following message: "Error in 'fields.legalConsentOptions'. Field 'legalConsentOptions' didn't pass validation.". As I said, no change were made from our side, and all prior submissions were working as expected. Is this update live? Is anyone else experiencing this error?

0 Upvotes