Updates to Contacts, Forms API and validation

forms

#1

Your contacts, and their data are the lifeblood of your HubSpot portal. The accuracy, and validity of this data is key, to rest assured that your team have the right information to work with, and your portal is moving smoothly. In an effort to ensure that all data coming into your Contacts is accurate, we’re releasing two updates soon to Forms that will make sure your data is valid and you’re equipped with the info necessary to know when and why it’s not accurate. The first update we’re introducing is to provide warning inside Forms when there are values that are invalid, and the second is to help fix some of these invalid values where possible.

Validation failure warnings

First up, we’re introducing error reporting into the new Forms Submissions app that will highlight any time a value was passed in via a form submission, that is not valid for the corresponding contact property. This will be shown in the submission sidebar as a yellow warning triangle beside any value that is invalid.

Some examples of cases where a submission value may not be valid are below.

Property doesn’t exist

If you pass a value in for a property that does not exist, this cannot be sent to the contact record. We’ll now highlight these right inside forms with the following warning:

Invalid option in enumeration property

The Forms API and Contacts API use the internal names of properties and property values. This is no different when sending values into an enumeration property (dropdown, radio buttons, single/multiple checkbox). In this case, the option ‘Yes’ for ‘Do you like peanut butter?’ is ‘true’. ‘Yes’ was sent over via the Forms API, and this is an invalid internal name.

What you’ll see inside Form Submissions:

In the property:

The same applies if the value is not cased correctly. ‘true’ is valid, whereas ‘True’ or ‘TRUE’ or ‘tRUE’ are not.

Invalid date

HubSpot APIs look for a timestamp to be a UNIX formatted timestamps in milliseconds, as outlined in our API documentation here. For ‘date’ properties inside Contacts, the UNIX millisecond timestamp also needs to be aligned to midnight UTC on that date, mentioned in the same article. If a timestamp being passed into a date property is formatted incorrectly (for example, contains a decimal point, non-number character or is not UTC midnight aligned) you may see the following error inside the Form Submissions app:

Invalid integer/number

Number properties inside HubSpot accept integers or one-point decimal numbers, i.e. 1.23 (not 1.2.3). You may see values fail to be passed into Contacts because they are invalid number. In the below example, the word ‘Around’ and a space has been passed into the number property ‘How many spoons of peanut butter do you eat a day?’.

Read only property

There are several properties in HubSpot that are computed by various systems including Forms, Analytics and Contacts, for example ‘Number Of Form Submissions’, ‘First Conversion Date’, ‘Number Of Pageviews’, etc. These properties can only be set by HubSpot and cannot be set by the Forms API or by the Contacts API. If a value is sent from Forms into one of these properties you will see the following warning inside Form Submissions:

Value matching/fixing

In addition to the validation reporting outlined above, we’re going to begin helping fix data where we can. Some of the areas where we’ll begin automatically fixing data are around date properties.

As outlined above, HubSpot looks for timestamps to be in UNIX milliseconds aligned to midnight UTC. In the event that a value is sent over that is unambiguous, we will automatically fix the value for you. For example, turning ‘2017-06-19’ (YYYY-MM-DD) or ‘2017-06-19T00:00:00.000Z’ (fully formatted timestamp) or ‘2017-06-19T00:00:00-04:00’ (timestamp with timezone offset) to the correctly formatted ‘1497830400000’.

The second value matching/fixing is around enumeration properties in HubSpot (radio buttons, dropdown, single/multi checkboxes). We will attempt to match the value passed through to the Forms API to both the label and the internal value for the property. This means that the above example where ‘Yes’ was sent through, will be fixed before being sent to Contacts.

Note: We do not recommend relying on the above value fixing/matching as it will change in the future. It is an attempt to help fix any existing issues users may see with values they’re sending into HubSpot today but it not something that will ever be expanded on or exist indefinitely.

This is the first update in a long list of improvements we’re looking to make to the Forms API, including providing validation directly on the Forms API. We hope these updates help ensure that you’re always getting the most accurate and usable data into HubSpot for you and your team. If you have any questions on these updates, or any thoughts on how we can help out further, please let us know.