Developer Announcements

rhenry
HubSpot Employee
HubSpot Employee

Upcoming Validation Change to the Forms API Submission Endpoints

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

 

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
2 Replies 2
advance512
Contributor

Upcoming Validation Change to the Forms API Submission Endpoints

We had an issue wit this.

 

Before, forms didn't require to add Fields (=properties) to them. If the fields were valid, the forms worked. We had a form with no Fields in it, except for the email, so we had complete flexibility in the dev side. It worked.
After the change, for forms created from March 22 and onwards, you need to include all relevant fields explicitly in the form. 

 

Forms older than March 22 should still work with the previous behavior, this is what Hubspot say.

But for some reason, it won't work with newer fields created after March 22, even if the form is older.
It's like what they said about the granularity is wrong - it's about the date of the fields that are used in the form, not the the date of the form itself.

 

We added the Field to the old Form (marked it as not required) and it worked. All older Fields that were submitted via the Form without being added, still work. Weird.

0 Upvotes
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